URL Builder Button Tool

The URL Builder Button is a tool that allows a Community Hub Admin to create a custom link through a button on a card that can pre-populate information on another page or an authorized 3rd party site.

At this time, the URL Builder Button Tool is a Support Enabled Feature. If this is something you are interested in, please reach out to Nimble AMS Support. You will not be able to complete following steps until this feature has been enabled.

Creating a URL Builder Button

Creating a URL Builder Button with the Current User's Salesforce ID

As an example, if you would like to create a URL Builder button that accesses a site with a query string parameter appended to a specified URL, you would need the query string parameter to be set to the current logged in user's account ID.

1. Defining the Button
   1. Navigate to the ‘Community Hub Setup’ App and select Buttons from the top navigation menu.
   2. Create a new button.
   3. Provide a button name.
   4. Set the class to URLBuilderButton.
   5. Provide a label for the button's text.
   6. Optional: Indicate the location for the button on the page.
   7. In the URL field, enter the web address.

   8. Click Save.

      

      Setting the Target field will not have an impact on the redirect process. The user will be redirected to the URL specified in their current browser window/tab.

2. Defining The Parameter
   1. From Setup, search ‘metadata’ in the quick find selection and select Custom Metadata Types.
   2. Find the Button URL Parameter metadata type and click on the Manage Records link.
   3. Click on the New button to create a new button URL parameter record.
   4. Provide a name for the parameter in the Label field.
   5. Specify the name of the parameter in the Button URL Parameter Name field. This can be the same as the Label value but it cannot contain any spaces or other punctuation characters.
   6. Check the Active checkbox.
   7. Since this is for the account ID, you can leave the query name blank.
   8. Set the query string parameter name in the Parameter Name field. This is the value that will be included in the query string of the URL.
   9. Set the Parameter Value field to {!CurrentAccountID}.
   10. Click on the lookup icon and select the button you created in the previous steps.
   11. Click Save.

3. Add the Button to Community Hub Content

   1. Return to Community Hub Setup.

   2. Select the page you want to include the button.

   3. Add the button to one or more cards on the page.

   4. Save the content.

Creating a URL Builder Button with Static Parameter Values

If you would like to create a URL Builder button that accesses a site with a query string parameter appended to a specified URL, this query string parameter will not be based on the current user or any other source of data but is instead a static value. However, the creation and inclusion of the button on a page is the same noted above section - the only difference is in the setup of the button parameter metadata record.

1. Define the Static Parameter

   1. Access Salesforce Setup and type metadata into the quick find selection to access the Custom Metadata Types.

   2. Find the Button URL Parameter metadata type and click on the Manage Records link.

   3. Click on the New button to create a new button URL parameter record.

   4. Provide a name for the parameter in the Label field.

   5. Specify the name of the parameter in the Button URL Parameter Name field. This can be the same as the Label value but it cannot contain any spaces or other punctuation characters.
      
      

      

      Since this is for the account ID, you can leave the query name blank.

   6. Check the Active checkbox.

   7. Set the query string parameter name in the Parameter Name field. This is the value that will be included in the query string of the URL.

   8. Set the Parameter Value field value to the appropriate value.

   9. Click on the lookup icon and select the button you created in the previous steps.

   10. Click Save.

Creating a URL Builder Button using a Query Record

If you would like to create a URL Builder button that accesses a site with a query string parameter appended to a specified URL, then this parameter's value should be based off of an accessible query record.The creation and inclusion of the button on a page is the same as above. The only difference is in the setup of the button parameter metadata record; the remainder of the steps are as outlined in the initial example above.

1. Define the Dynamic Parameter Using a Query Record

   1. Access Salesforce Setup and type metadata into the quick find selection to access the Custom
      Metadata Types.

   2. Find the Button URL Parameter metadata type and click on the Manage Records link.

   3. Click on the New button to create a new button URL parameter record.

   4. Provide a name for the parameter in the Label field.

   5. Specify the name of the parameter in the Button URL Parameter Name field. This can be the same as the Label value but it cannot contain any spaces or other punctuation characters.

   6. Check the Active checkbox.

   7. Set the Query Name to the name of the query record to use (query record setup is outside the scope of this guide).

   8. Set the query string parameter name in the Parameter Name field. This is the value that will be included in the query string of the URL.

   9. Set the Parameter Value field to the field name to grab from the query.

   10. Click on the lookup icon and select the button you created in the previous steps.

   11. Click Save.

Creating a URL Builder Button Using the Record ID

The parameter button can be used in conjunction with the current record or associated record as in the case of record lists and record sets. These objects include a reference to the related object's context. The remainder of the needed steps are noted in the original example above.

1. Define the Dynamic Parameter for the Current Record ID

   1. Access Salesforce Setup and type metadata into the quick find selection to access the Custom Metadata Types.

   2. Find the Button URL Parameter metadata type and click on the Manage Records link.

   3. Click on the New button to create a new button URL parameter record.

   4. Provide a name for the parameter in the Label field.

   5. Specify the key for the parameter in the Parameter Name field.

   6. Enter {!RecordId} in the Parameter Value field. This will indicate the button should use the record Id of the object identified in the context.

   7. Check the Active checkbox.

   8. Click on the lookup icon and select the button you created in the previous steps.

   9. Click Save.

Referencing a Merge Field in a Query

The URL Builder Button has special support for passing its record Id into a query. Record Id is a property buttons can use when placed on certain types of cards (notably Record List). To access the record Id in a query, simply place {!RecordId} wherever it should be referenced in the WHERE clause. {!CurrentAccountId} is also supported.

Parameterizing the URL Path

Some websites use a URL scheme like https://example.com/resource/{id}/additional/ , where {id} is a dynamic value. This dynamic value is not part of the query parameter string (i.e. there is no ? or &). To handle these cases, a couple adjustments are needed:

1. The URL on the Button record needs at least one string format token
   e.g. https://example.com/resource/{0}/dostuff/

2. They must be in order, and the first must be {0}

3. Any number are supported e.g. https://example.com/resource/{0}/dostuff/{1}/another/{2}/{3}/

4. The ButtonUrlParameter metadata records that provide the values have two differences:

5. The Type field needs to be changed to "Path Parameter"

6. The Parameter Name field needs to simply be a number corresponding to which place it should be
   substituted e.g. 0 or 1

7. A ButtonUrlParameter of Type Path Parameter and Parameter Name of 0 will have its Value substituted
   for the {0} in the URL

Dynamically Determining the URL

For each potential URL, you need to create a Dynamic Url Setting custom metadata record.

Do you have a single button that needs to go to two or more different URLs depending on certain conditions? If so, this is the section for you. The way the button determines which URL to use is as follows:

1. Dynamic URL Setting custom metadata records have three fields: Field, Data Source, and Value.

2. Field is the API name of a field on an object, e.g. NU__Member__c

3. That field is read from the first object returned by the Data Source.

4. If the value of the field returned by the data source matches the Value of the Dynamic URL Setting, that settings URL will be used.
   
   

   

   If none of the Dynamic URL Settings conditions are met, the URL on the Button custom metadata record is used.

5. Access Salesforce Setup and type metadata into the quick find selection to access the Custom Metadata Types.

6. Find the Dynamic URL Setting metadata type and click on the Manage Records link.

7. Click on the New button to create a new Dynamic URL Setting record.

8. Provide a name for the setting in the Label field.

9. Use the same value without spaces for the Dynamic URL Setting Name.

10. Choose the Button this setting corresponds to.

11. Specify the URL in the URL field.

12. Specify the Data Source to use for determining if this records URL is the one that should be used.

13. Set the Field to the API name of the field that the URL should look at.

14. Set Value to the expected value of the field.

15. Optionally, change the Sort Order. This is only necessary if some conditions need to be checked prior to others.

16. The first Dynamic URL Setting whose condition is met is the one that will be used.

17. The Dynamic URL Strategy can be ignored - it defaults to DataSourceFieldDynamicUrlStrategy which is the only option currently supported.

18. Click Save.

URL Builder Button with Multiple Parameters (Example)

For this example we will satisfy the use case of a button that should include three query string parameters, as defined in the table below:

Create the Button

We will start with the creation of the URL Builder Button definition in Community Hub Setup. Be sure to indicate URLBuilderButton as the button class. 

Learn more about Creating Buttons

Create the Parameters

Next, create each of the parameters by adding new Button URL Parameter metadata type record. Use the table below as a reference for each entry.

{!CurrentAccountID}

Add the Button to the Page

On a new or existing page, the button created in the first step can be added to any card that supports buttons. When the page loads and the button is clicked, the user will redirect to the specified URL with the ID, Pass Code, and Last Name parameters filled in.

Automatic Redirection with Parameters

Using the Redirect Page Handler in Conjunction with URL Builder Buttons any URL Builder button you create can be manually invoked on pages they are displayed or automatically through a special redirect handler in Community Hub. All that is required for automatic invocation is to use the special /redirect handler in Community Hub and specify the button you wish to execute by its name. The URL to call follows the format: https://<Community Hub URL>/communityhub/redirect?button=<button name>

If a user is not already authenticated, the redirect handler will ensure they log in before redirecting them to the target URL.

Redirect Example

The use of URL Builder Buttons with the redirect handler works very well for simple single sign on (SSO) operations that require the external site to capture some basic information of the logged in user without the need for complex integrations or workflows. The external site just needs to call on the /redirect page and specify the special URL Builder Button that will return the authenticated user to their site with query string parameters indicating user identity, authorization codes, or any other required parameter.

The button's name used in the redirect handler is case sensitive. You must ensure the button name in the redirect URL matches the name defined in the button configuration exactly. Button invocation using the redirect handler is not inhibited by access controls. If a button has an access control setting, the logged in user can still invoke the button's redirect actions regardless whether the individual meets the access control requirements.

Page Submission

If you need a button that submits the page the same way NC.SubmitButton does, use UrlBuilderSubmitButton as the class instead of UrlBuilderButton.

Community Hub Template Viewer

Using the URL Builder Button Tool, you can make Nimble Create Templates easily available for your constituents to access in Community Hub.

Requirements

Ensure the Community Hub Login User has:

• Object Permissions: Read access and View All for NUTPL__Template__c
• Visualforce Page: DynamicTemplate

As a general rule you should never give a profile the "View All" permission for an object. However in this case, it is necessary for Templates to function in this scenario.

Usage Guide

Basic Use

Create a button or nav that links to /apex/DynamicTemplate?templateName=My+Template&param1=someId

The only required parameter is the template name (replace spaces with +). Nearly all templates however take in a record id as a parameter, which you may specify using the URL. As an alternative, you can use Custom Parameters, as noted below.

Adding Custom Parameters

Use in conjunction with the URL Builder Button Tool to pass parameters into the template.

Changing the Orientation

Set the "landscape" URL parameter to "true" (i.e. add &landscape=true) to output in landscape mode, or, "false" to output in portrait mode. If the parameter is not set it will default to portrait mode.

The output may not show as the correct orientation in a print preview window. If on Windows and using "Microsoft Print to PDF" it is not possible to change the orientation.

Rendering as PDF

Set the "renderAs" URL parameter to "pdf" (i.e. add &renderAs=pdf) to render the template as a PDF, or, set it to "html" to output in html. If the parameter is not set it will default to HTML. As an example, you could use the following format:

/apex/DynamicTemplate?templateName=My+Template&param1=someId&RenderAs=pdf

Custom styles are currently broken for PDFs. It is recommended to output to HTML and then use the browser's print function to output PDF files.