How to make a connected app

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

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.
  
  
  

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.

• Example: artemis-dev1-dev-ed.my.salesforce.com

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.

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

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.

Page viewers can filter end results as needed.

This filter will not affect results for other users.

Sort results

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

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