3 - FCR SupportAPI Class III

The FCR_SupportAPI class exposes a number of global static methods that you can call from your APEX code to integrate your application with the Response Management Application. Access it from your application using the full name including the namespace:

FCRM.FCR_SupportAPI.

AssociateOpportunities

Void AssociateOpportunities(List<Id> ops, Integer numberPerAsyncRequest, DateTime targetTime)

Parameters:

ops = A list of opportunities that are not associated to responses yet.

numberPerAsyncRequest (Optional) = number of opportunities to include in each association async request. Default = 200.

targetTime (Optional) = Date-time that the first async request should be processed. Default = NOW() + delay specified in Opportunity Association config page.

Creates asynchronous requests to associate Opportunities to responses in the manner described in the Opportunity Association configuration page. If the opportunities are already associated (the opportunity field FCRM.FCR_Response_ID__c is not null) they will be ignored by the system.

As the description suggests, these opportunities will not be associated synchronously, so while this method can be called from Visualforce controllers and automation flows, the actual association will take a few minutes to complete. Although it can be paired with ExecutePendingAsyncNow() for synchronous calculation.

AssociateOpportunitiesToResponses

Void AssociateOpportunitiesToResponses(List<Opportunity> ops)

Parameters:

ops = A list of newly created opportunities

The Response Management Application maintains an association between opportunities and the response that was active when an opportunity was created. It does so by retrieving the active response for the contact associated with the opportunity when it is created. It can do this because, when an opportunity is created from a contact, a primary OpportunityContactRole object is created associating the contact with the opportunity.

When creating opportunities from APEX, it is not possible to create the OpportunityContactRole object until after the Opportunity is created. The AssociateOpportunitiesToResponses allows you to correctly create new opportunities using APEX and associate the correct active responses.

The sequence to use is as follows:

• Create the opportunities and insert them using the Insert DML statement. Note you may need to use the SetPassiveModeInContext API
• Create a primary OpportunityContactRole object to associate the newly created opportunities with the creating contacts (each of which may have an active response).
• Call AssociateOpportunitiesToResponses to associate the responses to the opportunities.

Internally, this method performs the following operations:

• Finds the primary contacts for the opportunities.
• Finds the active responses for those contacts.
• In active mode: enforces the presence of an active response on the primary contact.
• Initializes fields on the opportunity and active response
• Setting first/last touch for the opportunity if there is an active response
• Setting funnel fields in opportunity passing mode

This method can be called from a VisualForce controller or APEX trigger with the following caveats:

• This method performs DML operations on the opportunities and associated contacts and responses. As such, when called from VisualForce it must be called during an action or from a component that is marked to allow DML.
• This method should not be called during the before trigger of any object that can be modified by this method.
• This method should not be called during a trigger that is a result of a DML operation caused by the Full Circle Response management system. Doing so will result in the exception "Attempt to start an API, Visual Force or Future sequence during existing sequence"
• When calculating first touch on the opportunities, if a first touch date filter is enabled, the filter will be based on the current date and time regardless of the created date of the opportunity. In other words, the function assumes that the opportunity is newly created. If this is not the desired functionality, you can update the first touch date using the SetFirstLastTouchOnOpportunities or SetFirstLastTouchOnAssociatedOpportunities functions.

Typical Scenarios:

A VisualForce Opportunity Renewal button could allow selection of a primary contact that does not currently have an open opportunity, create a new response on that contact, and then either clone or reopen that opportunity, set the new primary contact, and call this method.

An Apex after opportunity update trigger could detect an opportunity being reopened, check if it has a primary contact, and if so create a new response for that contact if one is not currently present, then call this method to associate that response to the opportunity.

DisableApplicationForContext

void DisableApplicationForContext()

Use this method to disable the ResponseManagementApplication for the duration of this context call or until a subsequent call to UndoDisableApplicationForContext. This method is provided to aid in the implementation of specialized business processes and should only be used in consultation with Full Circle Insights or Full Circle Insights partners. Incorrect use of this method can lead to loss of data in the Response Management Application.

Apex code example:

// This statement disables the application
FCRM.FCR_SupportAPI.DisableApplicationForContext();

// Your Apex code here

// This statement re-enables the application
FCRM.FCR_SupportAPI.UndoDisableApplicationForContext();

ExecutePendingAsyncNow

void ExecutePendingAsyncNow(ID AsyncID)

Parameters

• AsyncID - The ID of an FCRM__FCR_Async_Request__c object to execute immediately. The object must not be in error status. Null to execute the oldest pending object

This API executes a pending asynchronous request immediately. It is intended primarily to be used in the Developer Console via anonymous Apex to allow rapid debugging of scheduled operations that would otherwise require long delays in order to debug.

This function will execute the asynchronous request immediately and ignores user context (i.e., it will always execute in the current user context).

ExecuteUtility

This method provides the ability to run various utilities within the application. It is best to consult with Full Circle prior to using any of them.

void ExecuteUtility(List<String> params)

Parameters:

• params - The first element of this list will always contain the name of the utility to run. Subsequent elements will have varying values, depending on the utility.

Utilities

Below are the utilities that can be run using the ExecuteUtility method.

Delete Deferred Update Item Records

The FCRM__FCR_DeferredUpdateItem__c object stores information that the application uses to try to recover from situations where it was not able to make an update due to row locking conditions. If there is a need to delete these records in bulk, this utility can be used to start a batch job to handle it. A date can be provided to only delete records on or before that date. If no date is provided, then all records will be deleted.

// This script will delete all deferred update item records in the org
List<String> params = new List<String>{'deletedeferredupdateitemrecords'};
FCRM.FCR_SupportAPI.ExecuteUtility(params);

// This script will only delete deferred update item records that were created on or before the date passed as the second parameter
List<String> params = new List<String>{'deletedeferredupdateitemrecords', '06/06/44'};
FCRM.FCR_SupportAPI.ExecuteUtility(params);

Delete Influence Request Records

The FCRM__FCI_InfluenceRequest__c object stores information that the campaign influence sub-system needs in order to do its processing. If there is a need to delete these records in bulk, this utility can be used to start a batch job to handle it. A date can be provided to only delete records on or before that date. If no date is provided, then all records will be deleted.

// This script will delete all influence request records in the org
List<String> params = new List<String>{'deleteinfluencerequestrecords'};
FCRM.FCR_SupportAPI.ExecuteUtility(params);

// This script will only delete influence request records that were created on or before the date passed as the second parameter
List<String> params = new List<String>{'deleteinfluencerequestrecords', '06/06/44'};
FCRM.FCR_SupportAPI.ExecuteUtility(params);

ActiveResponseStatusValues

Set<String> ActiveResponseStatusValues()

Returns

A list of all response status values that are active.

GetActiveResponses

List<CampaignMember> GetActiveResponses(List<ID> LeadOrContactIDs)

Parameters

• LeadOrContactIDs – A list of lead or contact IDs. All IDs must be of the same type (lead or contacts)

Returns

A list of CampaignMember objects that are active responses for the specified leads or contacts. Excludes responses that are opportunity active (active open opportunity status and related to an open opportunity).

Use this method to obtain a list of active responses on leads or contacts.

GetActiveAndOpActiveResponses

List<CampaignMember> GetActiveAndOpActiveResponses(List<ID> LeadOrContactIDs)

Parameters

LeadOrContactIDs – A list of lead or contact IDs. All IDs must be of the same type (lead or contacts)

Returns

A list of CampaignMember objects that are active responses for the specified leads or contacts. Includes responses that are opportunity active (active open opportunity status and related to an open opportunity).

Use this method to obtain a list of active responses on leads or contacts.
Note – when used with leads, has the same results as GetActiveResponses.

GetAutoCascadeLevels

Integer GetAutoCascadeLevels()

Returns

The maximum number of levels to auto-cascade, 0 means cascading is off.

GetContactStatusFieldName

String GetContactStatusFieldName()

Returns

The configured name of an alternate contact status field. Null to use the default native FCR_Status__c field

Note: Placeholder function returns null pending implementation in a forthcoming patch

GetCurrencyConversionMap

Map<String, Double> GetCurrencyConversionMap()

Returns

A map where the key is the ISO code and the value is the conversion rate to the corporate currency.

Multiply a currency value by the value in this map to obtain the value in the corporate currency. Does not factor in dates when advanced currency management is used.

GetEvaluationThreshold

Integer GetEvaluationThreshold

Returns

The evaluation threshold used internally to determine if a response score is qualified to be evaluated. (Responses that do not pass this threshold are generally set to Resolved – No action required.

GetResponsePromptCampaignIDs

Set<ID> GetResponsePromptCampaignIDs

Returns

A set containing the campaign IDs of the campaigns configured as response prompt campaigns.

GetScoringInfo

String GetScoringInfo(String objectType)

Returns

The field configured to use for scoring for the specified object. objectType can be one of 'Campaign', 'CampaignMember', 'Contact' or 'Lead'.

IsApplicationEnabled

Boolean IsApplicationEnabled()

Returns

True if the application is currently enabled. False otherwise.

IsInfluenceEnabled

Boolean IsInfluenceEnabled()

Returns

True if Campaign Attribution FMA license parameter is enabled. False otherwise.

IsLeadOrContactStatusActive

Boolean IsLeadOrContactStatusActive(String status)

Returns

True if the specified status is considered an active status. False otherwise.

IsLeadOrContactStatusSalesAccepted

Boolean IsLeadOrContactStatusSalesAccepted(String status)

Returns

True if the specified status is considered a status that is Sales Accepted. False otherwise.

IsNonResponseByRecordType

Boolean IsNonResponseByRecordType(Lead ld)
Boolean IsNonResponseByRecordType (Contact ct)

Parameters

ld, ct – A lead or contact to test

Returns

True if the specified lead or contact belongs to a non-response record type.

Note: If the lead or contact supports record types, you must query for the RecordTypeID field is the object you are passing as a parameter to this function was obtained via a query (as compared to a trigger)

IsPassive

Boolean IsPassive(Lead ld)
Boolean IsPassive(Contact ct)

Parameters

ld, ct – A lead or contact to test

Returns

True if the specified lead or contact is processed in passive mode.

This method takes into account all of the criteria for the IsPassiveMode call, and considers if the lead or contact is a passive record type.
Note: If the lead or contact supports record types, you must query for the RecordTypeID field is the object you are passing as a parameter to this function was obtained via a query (as compared to a trigger)

IsPassiveMode

Boolean IsPassiveMode()

Returns true if:

• This is a passive org or…
• The org is temporarily forced into passive mode (see SetPassiveModeInContext) or
• The current user is a passive mode user or
• This is a unit test that is not part of the response management application.

IsRepeatResponseUser

Boolean IsRepeatResponseUser(ID userid)
Parameters
userid – The userID to test, or null to test for the current user
Returns
True if the specified user is considered a repeat response user, false otherwise.

IsResponseSelectionInProgress

Boolean IsResponseSelectionInProgress

Returns true if the execution context is currently processing a campaign member insert through use of a response selector component (response prompts, or global response selector component).

This function would typically be called during a trigger or plugin API event to distinguish between associations to response prompt campaigns through the API or general UI, or through explicit action by a user using our response selector component.

Notes

• This function is specific to the response selector components only. Using the API function TreatNextCampaignAssociationAsResponsePrompts does NOT cause this function to return true.

PerformResponseSync

Map<ID, Database.SaveResult> PerformResponseSync(Set<ID> sourceids, Set<ID> responseids, Integer ObjectType, Map<ID, Integer> changeflags)

Parameters

sourceids – A Set of the lead or contact IDs that are the source of the sync. A single call to this function may include either lead IDs or contact IDs, but not both.
responseids – A set of the CampaignMember IDs that are the destination for the sync
ObjectType – 0 for leads, 1 for contacts
changeflags – A map from the lead or contact ID to the integer changeflag value (see description below)

Returns

A Map of Database.SaveResult values where the key is the ID of the CampaignMember that could not be synced and the value is the corresponding SaveResult object. Rturns null if no errors occur.

This function allows access to the internal response syncing mechanism of the Response Management application.

Typical Scenarios:

tbd

Change Flags: Use an 'or' combination of the following values to specify the scenario that you wish to sync:

Value	Description
1	Source status has changed
2	Source owner has changed
4	Source sync field has changed
256	Source status was previously active (current status is not active)
512	Source is newly created (first status change after create)
1024	Source status was previously inactive (current status is active)

Notes:

• On orgs using person accounts, use the shadow contact ID, not the Person Account ID, for the purposes of this function.

ReportDiagnosticInfo

void ReportDiagnosticInfo(Exception ex, String message)

Adds diagnostic information to the Response Management application event log.

Parameters

ex - An exception object to report (optional)

message - A text string to include with the event. Auto truncated to 1024 characters

Notes:

• Each call to this function results in an immediate DML operation (Data insert or update). Do not use this function within a loop, instead, collect the data you want to store and make a single call outside of the loop.

ResetInternalState

void ResetInternalState(String resetType, List<String> params)

Used to reset the internal state of RM - typically used after a rollback

Params:

String resetType: Type of operation to perform
List<String> params: Varies by resetType

ResponseStatusValues

Set<String> ResponseStatusValues()

Returns

A list of all response status values.

ScheduleAsyncOperation

void ScheduleAsyncOperation(String uniquepluginname, DateTime scheduledtime, String params)

Schedules an scheduled apex operation on the internal scheduler. When the specified time is reached, a 'TimedAsync' Schedule asynchronous event will be called on the specified plugin.
Notes:

• If the scheduled time is before the current time, the current time is used.
• The params string is limited to 32K in size or an error will be thrown.
• The specified plugin must be configured to receive the 'TimedAsync' event type or an error will be thrown.

SetDefaultFieldValuesForTest

void SetDefaultFieldValuesForTest(List<SObject> objs, Set<String> excludeFields, Boolean overrideNullsOnly)

Parameters

objs - A list of SObjects of type Lead, Contact, Campaign, Opportunity, Account, CampaignMember, User, Event or Task

excludeFields - A set of fields that should not have their default value set if one is available. Field names should be in lower case.

overrideNullsOnly - True to only override a field if it is currently null

The response management application supports the use of a pre-deployment resource file (static resource name FCR_TestInitializationData) to set field values on test objects. This API allows extension packages to leverage that capability to initialize field values on test objects using that resource.

Notes:

• This function has no effect when running outside of a unit test.

SetDefaultTestConfiguration

void SetDefaultTestConfiguration(Integer autoCascadeLevels, Boolean passiveMode)

Parameters

autoCascadeLevels - The default number of repeat responses allowed in this configuration. The maximum number is 10

passiveMode - The application should be configured in global passive mode

By default, when running a unit test with seeAllData=false, our application will be disabled as no configuration information can be found. This function can be used to enable the response management system during seeAllData = false tests. Generally speaking we recommend that you do not use this feature, and that all of your unit tests be designed to work with the application disabled. However, this function can be useful for integration testing.

Notes:

• Keep in mind that no other org configuration exists when seeAllData is false. The default configuration settings created by this function may not be compatible with your org. For example: field status mappings will not match your available field statuses. Workflows, processes and other features may not work correctly either.
• Calling this function has no effect outside of unit tests.
• Calling this function has no effect for unit tests where seeAllData = true

SetFirstLastTouchOnAssociatedOpportunity

void SetFirstLastTouchOnAssociatedOpportunity(ID opportunityID)

Calculates the first and last campaign touch on the specified opportunity that is associated to a response if they are not currently set.

After an association to an opportunity using the RCOA_ENABLEOPPORTUNITYASSOCIATION option during evaluation, first and last campaign touch are cleared on the opportunity. They are automatically updated during a later future call. However, when implementing association thorugh a VisualForce controller, it is sometimes preferable to perform the first/last touch calculation immediately on the opportunity in question. This function serves that purpose.

Returns with no error or effect if opportunityID is null.

Caution:

Do not call this function during a trigger or hook – it is intended for use from VisualForce controllers only. It is not bulk operation compatible.

SetFirstLastTouchOnAssociatedOpportunities

Set<ID> SetFirstLastTouchOnAssociatedOpportunities(Set<ID> opportunityIDs)

Calculates the first and last campaign touch on the specified opportunities that are associated to a response. This function updates first/last touch values even if they are currently set. If opportunityIDs is null, the operation will query up to 50 opportunties where both first and last touch are null, and attempt to set them.

If an opportunity specified by the opportunityIDs set is not associated with a response, that opportunity will be ignored.

Returns a Set of IDs of opportunities where the update failed.

Caution:

Do not call this function during an opportunity trigger or hook – it is best called during a future call

SetFirstLastTouchOnOpportunities

Set<ID> SetFirstLastTouchOnOpportunities(Set<ID> opportunityIDs)

Calculates the first and last campaign touch on the specified opportunities that is associated to a response if they are not currently set.

Unlike SetFirstLastTouchOnAssociatedOpportunity, this function will set first & last touch on a set of opportunities based on primary contact role if the opportunity is not associated with a response. This function will only operate on opportunities that have either first or last touch set to null.

If opportunityIDs is null, this function will perform the same operation as SetFirstLastTouchOnAssociatedOpportunities.

Returns a Set of IDs of opportunities where the update failed.

SetFirstLastTouchOnOpportunitiesAsync

Set<ID> SetFirstLastTouchOnOpportunities(Set<ID> opportunityIDs, Boolean UsePrimaryContacts, Integer delay)

Calculates the first and last campaign touch on the specified opportunities asynchronously.

Parameters

opportunityIDs - The list of opportunities to process. If null, will process the first 50 associated opportunities that have a null first or last touch value.

UsePrimaryContacts - If true, the primary contact (via OpportunityContactRole) will be used if there is no associated response and contact. Similar to SetFirstLastTouchOnOpportunities. If false, will only use associated responses.

delay - How long to wait to process the asynchronous operation. Specify -1 to use the organization default. 0 to process asynchronously as soon as possible. >0 to specify the delay in minutes to wait.

If opportunityIDs is null, this function will perform the same operation as SetFirstLastTouchOnAssociatedOpportunities.

Caution:

This function will throw an exception if the 2015 Async system is not enabled, or if it has been disabled for setting first/last touch.

SetRepeatResponseUserForContext

void SetRepeatResponseUserForContext ()

Use this method to treat the current user as a repeat response user for the duration of this context call or until a subsequent call to UndoSetRepeatResponseUserForContext. This allows you to perform campaign associations that include repeat responses when running under an account that normally cannot do so.

Notes:

• This function is distinct from the TreatNextCampaignAssociationsAsResponsePrompts method which causes response associations to be automatically qualified. The two functions can be used together.
• This function does not change the user for the execution context – thus does not change settings of fields such as OwnerID, hierarchy based settings, or other functionality based on the running user. It only treats the current user as a repeat response user.
• When used while entering a response, this setting does not apply to evaluation of passive status timeouts (i.e. timeouts do not apply to leads or campaigns created by repeat response users – calling this function will not cause the current user to be treated as an repeat response user for the purposes of this evaluation).

This method is provided to aid in the implementation of specialized business processes and should only be used in consultation with Full Circle Insights or Full Circle Insights partners. Incorrect use of this method can lead to incorrect data in the Response Management Application.

SetPassiveModeInContext

void SetPassiveModeInContext()

This method forces passive mode for the duration of the execution context. This may be used in active organizations to ensure that APEX operations are performed as a passive user.

SpecifyContextAsyncUserStatus

void SpecifyContextAsyncUserStatus(Boolean isAsyncUser)

Use this function to specify if the current context user should be treated or not treated as a delegated async user for the duration of this function. If unspecified, the current application settings will be respected for regular code and unit tests where SeeAllData is true. The current user will be treated as an async user for all other unit tests unless overridden by this function.
The delegated async user is one who has permission to perform asynchronous operations on behalf of other users. This API function is used primarily by extension packages for unit tests.

SyncSourcesToResponses

void SyncSourcesToResponses(Map<Id,Id> sourceToResponseIdMap, Boolean isUpdate)

Use this method to sync fields from either a Lead or Contact to a CampaignMember, in bulk.

sourceToResponseIdMap This is map of either Lead ID or Contact ID to CampaignMember ID.

• • Entries in this map must be either all Leads or all Contacts. If there are mixed entries, an exception will be thrown and no processing takes place.
  • For each entry Campaign Member must be associated to the specified Lead or Contact. If it is not, , an exception will be thrown and no processing takes place.

isUpdate This is used to determine what fields to sync based on the Sync Fields configuration data in the Response Management app.

TreatNextCampaignAssociationsAsResponsePrompts

void TreatNextCampaignAssociationsAsResponsePrompts()

This function, with a painfully long name, is used when you are inserting CampaignMember objects using Apex code. After you call this function, the next insertion of CampaignMember objects will treat all of the campaigns in the batch as response prompt campaigns. This means that each response will be considered qualified and evaluated as such regardless of score.

Example use case:

A trigger is implemented to associate campaigns based on information other than the score, such as the lead source value.
Important Notes:

• This option impacts the next campaign association only (next CampaignMember insert) and then resets. If you are performing multiple CampaignMember insert operations, you must call this function between each one.
• This option impacts all Campaigns during the next CampaignMember insert (one or more CampaignMember objects in a batch). If you have a batch of CampaignMembers to insert, and wish to treat only some of them as response prompt campaigns, split them into two batches and use this option only for the one where you wish to treat the campaigns as response prompt campaigns.
• If running as the Repeat Response user, this feature will still work – in this case also applying to updates to existing CampaignMembers that are evaulated as responses. This feature does not change the determination of whether or not a new CampaignMember is considered a response – it only impacts whether responses are considered qualified.
• This option disables the asynchronous scoring and processing option for the CampaignMember objects in question. This could lead to incorrect scores on those CampaignMember objects if you are using asynchronous scoring (but they will still be considered qualified as if they were response prompt campaigns).
• Because this option forces synchronous processing, you may see limit exceptions if you use it on larger batches. Reduces the batch size if this occurs.
• If response prompt notifications are enabled, they will also be enabled for CampaignMembers inserted with this option.
• This option does not treat the response as if entered through the UI – i.e., it does not automatically allow repeat responses (as it would through the UI). Use Response Evaluation Control field value RC_CREATECASCADES (2) to enable cascades.
• The configuration option "Do Not Trigger Assignments for Response Prompt Campaigns" does not apply and is treated as if false (i.e., normal assignment is always applied).

UndoDisableApplicationForContext

void UndoDisableApplicationForContext()

Use this method to reenable the Response Management Application after it has been disabled by the DisableApplicationForContext method.

UndoSetRepeatResponseUserForContext

void UndoSetRepeatResponseUserForContext()

Use this method to undo the previous call to the SetRepeatResponseUserForContext method.

UpdateAllResponseOpportunityAmounts

void UpdateAllResponseOpportunityAmounts()

Use this method to run a batch to update all opportunity amounts on CampaignMember objects on multicurrency orgs.

This can be called after a change in currency exchange rates, or to ensure values are updated quickly after data updates when the application is disabled (such as a data migration).

The system automatically picks up changes in currency exchange rates once every 24 hours.

UpdateCMArchives

void UpdateCMArchives(Set<ID> responseids, Boolean GoAsync)

Parameters:

Responseids – The ID values of the responses (CampaignMember objects) to update
GoAsync – True to perform the update asynchronously (See notes)

Use this method to update the archived value of the response (stored in the FCR_Admin_CMArchive__c field on its associated opportunity). This archived value is used to restore a response destroyed during a merge operation.

Notes:

This function will perform a DML update operation on the opportunities referenced by the FCR_Opportunity__c field on the CampaignMember objects. Use the async version of this function if called during any CampaignMember or a before-update opportunity trigger.

If the new asynchronous system is enabled (which is true by default), this method is always asynchronous.

If the advanced configuration "Block Archive Updates" field is set, this method will NOT update existing archives. To force an update in this case, you must first explicitely clear the opportunity FCR_Admin_CMArchive__c field.