Contact us Blog

Creating Apsona merge buttons in Salesforce pages

Here we describe how to create Salesforce custom buttons for Apsona merge actions. If you are unfamiliar with merge actions, please look at the documentation about merge actions. Once you have created a merge action, you can run it directly from a Salesforce custom button with one click. You can use this feature, for example, to generate a welcome letter to a new contact, a thank-you letter to a donor, or an invoice for a customer. Once you have set up the button, simply open the record's detail page and click the button, and the document is generated instantly.

You can also set up a custom link in a home page component to run a merge action. The home page component will appear in the left sidebar of every page in Salesforce, except the administration pages (see the screen shot at right).

Setting up custom buttons and links using merge actions is quite straightforward. Here are the steps.

Creating a custom button for a Salesforce detail page

  1. Navigate to the merge actions list by hovering your mouse over Settings and clicking Merge actions.

  2. In the list of merge actions that appears, find the one for which you wish to create a button. Click the row containing that merge action. The details for that merge action appear in the right panel. Click the button labeled "Make button" in the right panel.

  3. A popup window appears containing a list of the possible detail pages in which you can embed the selected merge action as a button. Select the detail page for which you want the button, and click the Generate button.

  4. Apsona generates the necessary code for the button and displays it in the panel below. Select and copy the generated code.

  5. Navigate to Setup in Salesforce, and select the Buttons, Links and Actions option for that object. Click New Button or Link.

  6. In the button creation screen, provide a name for the button, select "Detail Page Button" as Display Type, and select "Execute JavaScript" for Behavior. Paste the generated code into the text box below, and click Save. Your button is then ready for use in the layout.

Creating a custom link for use in a sidebar

To make the merge action available in a sidebar, you must create a custom link for the action, as well as a home page component to in which to house the custom link (unless you already have a home page component in which you will house it). You must then add the home page component to the home page layout for the profile that will use the merge action.
  1. Steps 1 through 4 are the same as above.
  2. In Salesforce, navigate to Setup - Customize - Home and click the Custom Links item. Then click the New button in the right panel.

  3. In the link creation screen, provide a name for the link, and select "Execute JavaScript" as Behavior. For the Content Source, select OnClick JavaScript, and paste the generated button code into the text box below. Then click Save. Your home page custom link will now be available.

  4. To create a Home Page Component in which to house the custom link, navigate to Setup - Customize - Home and click the Home Page Components link. Then click the New button under Custom Components.

  5. Provide a name for the new custom component, and specify its type as Links. Click Next.

  6. In the next screen, select the newly-created custom link and click Add to add it to the custom component. Then click Save. Your new home page component is now ready for use.

  7. Finally, add the new custom component into the layout for your profile. To do this, navigate to Setup - Customize - Home - Home Page Layouts. Click the layout into which you wish to add the new component.

  8. Click the Edit button. In the next screen, select the new component to appear in the Narrow Components section. Click Next, and then Save.

Selecting one of several actions

In some situations, you might need to create multiple merge actions for the same record, and to select one of those actions to run. For example, when viewing an Opportunity record, you might need a separate action for generating a proposal, a follow-up letter or an invoice. And you might wish to click the button, then select the appropriate merge action for the Opportunity, and run the action. You can set up such a detail page button with a bit of JavaScript code. Such a button, when clicked, displays a popup such as the one below.
  1. First, use the Apsona button code generator (above) to generate the JavaScript code for one of the merge actions. The code might look like this:
    /** Merge button code for action "Proposal letter" to use in detail page for Opportunity **/
    {!REQUIRESCRIPT("https://service.apsona.com/sfdc/apsona_inline.min.js")}
    apsona.runAction ("buttonMerge", {
        "element": this,
        "actionId": "a02i000000hadkvAAA",
        "recordId": "{!Opportunity.Id}",
        "linkFieldId": "Id"
    });
    
  2. Next, identify the record IDs for each of the merge actions you wish to include in your selector. You can find the record ID of the merge action by navigating to Settings - Merge actions, clicking a merge action row on the left, and viewing the detail panel, as in the screen shot below.
  3. Finally, modify the button code so that:
    • The text buttonMerge is changed to buttonMergeAfterSelect
    • The actionId attribute is replaced by the actions attribute, and the items in the actions list contain value and text pairs indicating the merge action id and the corresponding text to show in the selector.
    Below is an example of the modified button code.
      apsona.runAction ("buttonMergeAfterSelect", {
          "element": this,
          "actions": [
              {
                  value: "a01C000000lQLZIIA4", /* Id of the merge action */
                  text: "Proposal" /* Corresponding text to display in the selector */
              },
              {value: "a01C000000oVaaJIAS", text: "Follow-up letter"},
              {value: "a01C000000lQLZIIA4", text: "Invoice"}
          ],
          "recordId": "{!Opportunity.Id}",
          "linkFieldId": "Id"
      });
    

Creating a merge button for the Lightning Experience

To support merge buttons in detail pages in the Lightning Experience, you will need Apsona's Lightning Components for embedding such buttons. Here are the steps to create such a button. Only Administrators can perform these steps. Your org must have My Domain enabled before you can use this component.
  1. If you have not already done so, install our Lightning component from the installation URL:

    for production and developer orgs
    for sandbox orgs

    You will now have available a Lightning component named ApsonaDocGenButton in your org. You can examine this component via clicking Setup - Custom Code - Lightning Components in your org. We suggest that when you install the component, you choose to make it available to all users instead of admins only. This choice will make it easier to deploy the component, but you still have the ability to assign licenses via Manage licenses in Apsona.
  2. As with the Classic UI, navigate to Settings - Merge actions in Apsona, find the merge action you want to use, and click Make Button. The button generator popup appears.
  3. Click the Generate button, and select and copy the generated code.
  4. Within the Lightning experience, navigate to a detail record for the object for which you want the button, and start up the Lightning page builder via the Edit Page button in the Settings menu.
  5. Select the Apsona Doc Gen component from the Custom section of the Lightning Components panel and place it where you would like to appear in your page. In the screen shot below, we have created a new tab called Doc Gen and placed the component in the tab.
  6. Paste the copied code into the Action Code box. Provide the text for the Button Text and Prompt Text options as needed. Click Save.
  7. Your button will now appear in the Lightning page.

Common questions

How does Apsona determine which detail pages are available for a particular merge action?

Here are the possibilities:

Why is the "Home page component" choice unavailable for some merge actions?

If a merge action is constructed from either a report or a multi-step report, then it will be usable in a home page component. But if the merge action is constructed directly from an object (i.e., by clicking Tools - Merge/Mail in the object's menu in Apsona), then that merge action will not be available for use in a home page component. The reason is that, if it was created from a report, the report's designer will have applied the appropriate filter conditions to restrict the range of records to be used for the merge action. But if it was created directly for an object, then the merge action could potentially use all the records in that object for merging when invoked from the home page component — which is likely not what the designer intended.