Salesforce Views Server - User Guide

 

 

Current Version

Features

  • Detailed Views for common objects

  • Relationship views for pairs of objects (currently only supporting Accounts' Contacts)

  • Macro configuration for page editors is available from the page view

  • Multiple instances of the macro can be included in a single page

  • Page editors can limit results with query filter, affecting all usages of the macro

  • Page viewers can filter results further, affecting only themselves

  • Sort results in ascending and descending order

  • Page editors can choose the number of results to return when configuring the macro

  • Some features supporting keyboard commands

User Guide

Administrative requirements

Top level requirements for connecting Confluence to Salesforce:

  1. An HTTPS secured Confluence - Salesforce won’t allow connections from the HTTP prototcol

  2. A Salesforce connected app - where you register that your Confluence is allowed to make requests

  3. A Salesforce user - to authenticate with

  4. An OAuth dance - triggered once from the Confluence side in the Salesforce Configuration section of the admin console.

Read more for details on each of these requirements

HTTPS Secured Confluence

Requires HTTPS

Salesforce will not allow a connection to a Confluence that is not being served with the https protocol. If your Confluence is only available with the http protocol you will not be able to configure this plugin.

Salesforce Connected App

For step by step written instructions on how to setup a Connected app, scroll down a bit further. For screenshares on this topic:

 

 

Screenshare

Notes

Screenshare

Notes

How to make a connected app

Setting up a Connected App (step by step):

Screenshot

Steps

Screenshot

Steps

Navigate to the App Manager:

  • Login to Salesforce using an account with administrative privileges.

  • Go to Setup. (Click the gear at the top, click Setup.)

  • Using the Quick Find search, type in App Manager, and click App Manager.

 

Make a new Connected App

  • Click New Connected App

  • Input the following info into the fields:

    • Connected App Name: Artemis Confluence Connector

    • API Name: Artemis_Confluence_Connector
      Note: Clicking tab from previous field will automatically fill this field

    • Contact Email: your email

    • Contact Phone: your mobile

    • Logo Image URL: https://login.salesforce.com/logos/Custom/Gear_Purple/logo.png
      You can click the links below this field to either upload your own image or launch a popup with a massive set of pre-loaded options. This doesn’t make a big difference in terms of what you or users will interact with, so feel free to just pop that Purple logo described above in and forget about it.

    • Icon URL: https://login.salesforce.com/logos/Custom/Gear_Purple/icon.svg
      As with Logo Image URL you can click the link below this field for pre-loaded options, or just use the one suggested above.

    • Enable OAuth Settings: check

    • Callback URL: https://YOURCONFLUENCEURL/rest/artemis/salesforce/1.0/oauth/callback
      Your callback URL will be your confluence's baseurl + /rest/artemis/salesforce/1.0/oauth/callback.
      You can have multiple callback urls configured (useful if you have separate test and production Confluence servers). Separate each url with newlines.
      To identify your Confluence baseurl, login to Confluence, click the admin gear, click General Configuration. Your Confluence baseurl will be listed next to Server Base URL.
      Example:
      My callback url will be: https://esme.local:8443/confluence/rest/artemis/salesforce/1.0/oauth/callback
      if my confluence base url is:

    • Selected Oauth Scopes: Add the following two scopes:

      • Access and manage your data (api)

      • Perform requests on your behalf at any time (refresh_token, offline_access)

    • Click Save, then on the next screen Click Continue.

 

Identify the Consumer Key and Secret you will need for the Oauth Dance

After you’ve created your connected app, the View screen for the app will display.

You can get the consumer key and secret you will need from this screen.

You can also get there by navigating to the App Manager → Clicking the down arrow next to your connected app → Clicking View

What do the OAuth Scopes do? Why does the plugin need them?

The 'Access and manage your data' scope allows our plugin to make SOQL queries to Salesforce so that we can display your data in Confluence.
The 'Perform requests on your behalf..." scope allows us to request new access tokens when the old ones would expire, so that an administrator only has to go through the oauth dance once in order for the plugin to be configured. Otherwise, Salesforce authentication would be needed every time a token expires which occurs fairly frequently.

Salesforce Authenticating User

The Salesforce user that will be used to authenticate with Salesforce, make requests, and access data.

Screenshot

Requirement

Screenshot

Requirement

 

API Enabled

The Salesforce user must be a member of a profile with the 'API Enabled' permission turned on. (Setup -> Quick Find: Profiles, find the profile of the user you are interested in, Edit that profile, look for 'Api Enabled' and make certain it's checked.)

 

Review user license and object visibility

The Salesforce user must have view permissions for any data you wish to display with this Confluence plugin. If the authenticated user can't see it, then the plugin won't be able to see it either. Tips:

  • Make certain the user’s license supports access to the objects you want to display. For example, the Salesforce user license supports access to Case objects, but the Salesforce Platform user license does not. To change a user’s license, edit that user. Available licenses will be listed in a dropdown. You can see a listing of how many licenses you have remaining of which type through the System Overview. (Setup -> System Overview -> Most Used Licenses -> Show All -> User Licenses)

  • Configure the user's profile to control visibility of your Salesforce objects. (Setup -> Quick Find: Profiles, find the profile of the user you are interested in, Edit that profile, look for ‘Standard Object Permissions' and make certain the objects you want to make available have the Read permission checked.) If you only wish to change this particular user’s permissions (as opposed to everyone currently using that profile), you can clone the profile and edit that user to assign the new profile.

Optional: Pre-approve the app in the profile

You can optionally pre-approve this app for users in that profile. This speeds the oauth dance up by not requiring an explicit permission approval. Since the admin setting up the connected app is probably also the admin doing the one-time oauth dance, its not particularly critical. (Useful for dev ops loop, though.) To do this:

  • Setup -> Quick Find: App Manager -> Artemis Confluence Connector -> Manage -> Edit Policies -> Permitted Users: Admin approved users are pre-authorized.

  • Then, explicitly allow access to the app for users in the relevant profile. Setup -> Quick Find: Profiles, find the profile you are interested in, Edit that profile, look for 'Connected App Access' and make certain the Artemis Confluence Connector is checked.


The OAuth Dance - Connecting Confluence to Salesforce

The Oauth Dance is a standard way to securely connect unrelated apps. You’ve probably run into Oauth when connecting Google, Facebook, or many other apps to each other. The app requesting permission will redirect you in your browser to the app it wants permission to access. Typically, you the user will be requested to formally click an Acknowledge or Approval button in order for the requested app to share data with the requesting one. Administrators allowing this kind of integration are often required to setup keys and secrets that support the process. In this situation, you are going to wear both hats: Confluence admin setting up the keys and secrets allowing the integration, and Salesforce authenticating end user approving the oauth dance.

Screenshots

Dance Steps

Screenshots

Dance Steps

Salesforce profiles

You can have multiple Salesforce profiles with different urls, consumer keys, and secrets. This is helpful when switching between Sandbox, Scratch Org, and Production environments.

  • Login to your Confluence, navigate to the admin console, and then to the Salesforce Configuration screen.

  • Click Edit.

  • Edit the fields of your Salesforce profile.

  • Url: See below

  • For the Profile Name: You can name this anything you like, it will be used to save your profile settings on the server, and allow you to choose from between multiple profiles.

  • Consumer Key: This is populated by the Consumer Key setting from your Connected App. (Setup -> Quick Find: App Manager, find your app, click arrow on the right of it, choose View, Look for Consumer Key)

  • Secret: This is also from the Connected App. In the same place as the Consumer Key there is a Consumer Secret field. There should be a link next to it that says click to reveal. Click that to get the Secret.

 

The URL field

This is your Salesforce URL, so that Confluence knows where to connect to.

For best results, provide your My Domain setting (Salesforce -> Setup -> My Domain).

Alternatively, if you don't have and don't yet want to setup a My Domain, then you can use the server displayed in your URL bar after you've logged into Salesforce. This is less reliable for several reasons, including that it might get changed out from under you. Don't include the protocol.

Troubleshooting:

  • We’ve seen some failure to connect problems (occasional/inconsistent UnknownHostException errors) when using the lightning.force.com style domains. If you are experiencing this, please register a My Domain and use that instead.

What about Scratch orgs?

  • If you’re testing things out and want to use a scratch org, go ahead. You’ll still need to setup a connected app, but once everything’s in place, you can:

    • grab it from the url bar,

    • or use the list command to get the instance url.
      $ sfdx force:org:list --verbose

    • Either way, Don’t include the protocol when configuring the url in the configuration screen.

 

Requesting Salesforce Access

Click Save to save your profile settings to the server.

Your newly saved profile should automatically be set in the dropdown. (You can have multiple profiles, which is useful when you want to test a sandbox.)

To authenticate with the profile currently chosen in the dropdown, click Request Salesforce Access.

This will direct you to Salesforce, where you will login. If pre-authorized, that’s all you need to do. If not, you can then explicitly authorize the plugin to have access to the Connected App.

 

Connected!

When the process is complete you will be redirected back to the admin screen for the plugin. You should see that the Access Token and Refresh Token fields now list that they are Configured. Before the dance, they will say that they are Missing.

The plugin is now configured. Using macros in Confluence pages will use data from the Salesforce currently listed in the dropdown menu.

You can switch between configured profiles without needing to re-authorize, as long as you’ve authenticated once and the tokens have not been revoked on the Salesforce side explicitly by a Salesforce administrator.

Using the Salesforce View macro

Configuring the Salesforce View macro

Screenshot

Notes

Screenshot

Notes

Add macro to a page.

  • Edit a page.

  • Add the Salesforce View macro to the page.

  • Publish the page.

  • Configure the macro: Choose from the presented configuration dropdowns and Save.

Number of Results

To control the number of results, choose from the numbered dropdown:

Query Filter

To limit results with search terms, use the Query Filter textfield.

  • The filter will affect most text style fields for that object. Date, Number and ID fields are not supported. Some long text field objects (like Account description) are not supported. The field has to work with the SOQL LIKE operator to be affected.

  • Changes to the query filter will affect all usages of that instance of the macro. Example usages:

    • Limit a Contact Detailed view with query string “VP, Finance” to show results that have that title.

    • Limit an Account view with the query “Communications” to return Accounts with the industry Communications or Telecommunications.

  • The LIKE operators % and _ are supported.

    • The % wildcard matches zero or more characters.

    • The _ wildcard matches exactly one character.

    • Example usage: Use the query “b%” to only get results that start with a B (in any field that is supported though).

    • For more info on the SOQL LIKE operator and its wildcards: Salesforce Reference - WHERE Clause

Making changes to an already configured macro.

Any page editor can re-configure the macro by clicking the pencil/edit icon visible at the top of the macro

What does the end user see after the macro is configured?

There are two types of views: Relational and Detailed. Currently there is only one type of Relational view: Account/Contact.

Screenshot

Notes

Screenshot

Notes

Relational View:

Account/Contact will show a lists of Contacts organized by their related Accounts.

Detailed View:

Any Detailed view will show a list of that object and a set of pre-configured fields.

Additional Controls for Page Viewers

Even without control over macro configuration, page viewers have a lot of options for manipulating end results to quickly find what they need.

Screenshots

Notes

Screenshots

Notes

A search filter available to page viewers

Page viewers can filter end results as needed.

This filter will not affect results for other users.

End users can use sort buttons to organize results.

Sort results

Use the up and down buttons (keyboard commands u and d) to sort results in ascending or descending orders.

Keyboard Commands

Now supporting some keyboard commands:

Type:

In order to

Type:

In order to

u

Sort results in ascending order

d

Sort results in descending order

h

Navigates to the next Salesforce View macro in the page.

Right Arrow/Left Arrow → Enter

Once sort buttons are highlighted, use right and left arrows to switch between icons, then type Enter to choose that option. For example, page editors can type d then the Right Arrow, then Enter to launch the config screen.

[d][Right Arrow][Enter]

Triggers the config screen (if user has page edit permissions)

Tab

Once sort buttons are highlighted or macro has been navigated to (with h), use Tab to focus the filter.

Escape/Enter

Escape or Enter to leave the filter

Release Notes

Knowledge Base & Support Info

 

Related Articles

General Articles