1. Unifyr Admin Academy
  2. Administration & Settings
  3. Settings
  4. Labs

Set up a Labs SFDC Query

Avatar
Unifyr Support
Follow

Important

Labs SFDC Queries may need to be enabled on your system. Submit a request to your Unifyr One team if you want to output data in this way.

Setting up an SFDC Query will require advanced technical knowledge. We recommend consulting with your Salesforce Administrator or a designated engineer from your organization to help you set up an SFDC Query in Unifyr One.

Overview

SFDC Queries in Unifyr One allow you to display partner-specific data from your Salesforce environment to your partners in their partner portal account using SOQL.

The SFDC Query information is view-only on the partner portal. It simply pulls the raw data from SFDC and renders it to the partner portal using an angular template.

There are four main steps to setting up the query and displaying the data on the partner portal:

  1. Create a Credentials object or objects to hold credentials/authorization information - username/password or OAuth 2.0.
  2. Build the SFDC Query object and link it to one of the Credentials objects.
  3. Test how the query appears in the partner portal.
  4. Make the SFDC Query available to your desired partners in the partner portal - use a Dynamic Content widget that represents your query.

Use the sections below to complete each step.

Before You Begin

There are a few elements you will need before you can begin building the query:

  • Decide which method of security you will use for your connection to SFDC. Unifyr One supports the traditional username/password paradigm or authentication via OAuth 2.0. See the Create a Credentials Object section of this article for information.
  • Retrieve your Salesforce API Security Token, if required. 
  • Select which partner/user Merge Fields (data placeholders) you’d like to include in your query. See the Which Merge Fields does Unifyr One support for an SFDC query? section of this article for more information.
  • We recommend building a Partner Group for your internal team’s test partner portal accounts. You can use this Partner Group to filter the availability of your SFDC SOQL query data when testing the query. See the Test the SFDC Query section of this article for more information.

Note

If you would like technical help in setting up and testing the SFDC Query, submit a request to your Unifyr One team.

Contents

Click on the + to expand the instructions for the desired task.

Create a Credentials Object

Credentials objects hold connection credentials and authentication/authorization data.

When you create an SFDC query, you link it to one of your credentials configuration objects. If you need to update your credentials, make the change in the Credentials object and every linked query will use the new details automatically.

These types are available when you’re creating a Credentials object:

  • Classic - uses Username, and optional Password and Security Token

  • OAuth 2.0 - uses Client ID and Client Secret

    Selecting this option allows you to define the Grant Type, which defines how an access token is generated for a request:

    • Authorization Code
    • Client Credentials

To create a Credentials object:

  1. Navigate to   > Settings > Labs.
  2. In the SFDC Query area, click Manage.
  3. In the SFDC Queries page, go to the Credentials tab in the left sidebar.
  4. Click Create SFDC Credentials.

  5. In New SFDC Credentials, complete this information as required:

    Parameter Type Description
    Name Text The name of the credentials set.
    Active Toggle

    Whether the credentials are in use.

    If Active is set, you can select this credential set when creating a query, to link it for use.
    Authorization Type Dropdown

    Which type of security to use. Choose one of these:

    • Classic (Username and Password)
    • OAuth 2.0 (Client ID and Client Secret)
    Grant Type Dropdown

    The method to be used to acquire an access token to authorize a request. Choose one of these:

    • Authorization Code
    • Client Credentials

    This field is available if you've selected Authorization Type = OAuth 2.0.

    For information about the types, consult your OAuth 2.0 resource.
    Domain Text

    The domain of the SFDC application.

    Enter the full URL, i.e. https://[domain].my.salesforce.com
    Username Text The username for SFDC login.
    Password Text

    [Optional] The password for SFDC login.

    This field is available if you've selected Authorization Type = Classic.
    Security Token Text

    [Optional] The security token for SFDC login.

    This field is available if you've selected Authorization Type = Classic.
    Client ID Text

    The ID of the client making the request.

    This field is available if you've selected Authorization Type = OAuth 2.0.
    Client Secret Text

    The key for the client making the request.

    This field is available if you've selected Authorization Type = OAuth 2.0.
  6. [Optional] Click Test Credentials to confirm that you've entered valid information.
  7. Click Save and Authorize. The query is listed in the Credentials tab of the SFDC Queries page.

admin_labs_sfdc_query_credentials.png

Create an SFDC Query

To create an SFDC query, create an SFDC Query object then link it to an SFDC Credentials object, to ensure the necessary login/authorization credentials are always available when the query is run.

  1. Navigate to   > Settings > Labs.
  2. In the SFDC Query area, click Manage.
  3. In the SFDC Queries page, go to the Queries tab in the left sidebar.
  4. Click Create SFDC Query.

  5. In New SFDC Query, complete this information as required:

    Parameter Type Description
    Name Text The internal name for the SFDC query.
    Active Toggle

    Whether the SFDC Query is in use, and is actively pulling data from Salesforce. We recommend waiting to activate the query until you’ve entered all the necessary information.

    The Active toggle must be enabled to to test the SFDC Query.

    If the toggle is inactive, the SFDC Query will not return results.
    Credentials Dropdown Select the Credentials object that defines the login/authorization information for your Salesforce account.
    Scope Configuration Select

    Define if the platform should filter query results at runtime. This can protect against cross-partner data exposure without relying solely on the WHERE clause in the query.

    Choose one of these scope modes:

    • Scoped (default) - query results are limited to the authenticated partner's data

      A WHERE filter is injected at runtime using the SFDC Scope Field and Scope Value (Merge Variable) configured in the query. This is the safe default for any partner-facing query - the platform adds the partner filter as an AND condition, so cross-partner exposure is prevented regardless of the WHERE clause in the query.

    • No scoping - no partner data filter; cross‑partner visibility is possible.

      The query runs exactly as authored with no partner or user restrictions applied by the platform.

      Warning

      Use this option only when results genuinely need to span multiple partners (e.g. internal dashboards visible only to Unifyr staff or super-admins)
    SFDC SOQL Query Code

    The partner merge fields to use in the code. These merge fields will  pull in the relevant partner data from SFDC into the partner portal for each partner.

    Important

    Aside from the merge fields, the rest of the SOQL query is taken from your organization’s SFDC account. Consult your Salesforce administrator for questions about retrieving the necessary SOQL query.

    For information about the merge fields supported by Unifyr One, see the Which Partner Merge Fields does Unifyr One support? section of this article.

    For an example of a valid SFDC SOQL Query, see the Sample SFDC SOQL Query section of this article.
    Template Code

    The code that determines the formatting of the raw SFDC Query data when delivered to the partner portal.

    This is an Angular template that will render in the portal. There is a variable in scope called `queryResults` and `queryResults.list` could be used to access the list of elements in the query.

    Here, you can add options to sort the data by columns or export when the data is rendered on the partner portal.

    For an example of a valid template, see the Sample Template section of this article.
  6. Click Save to save the new query. You must test it before you can publish it to partners. For more information, see the Test the SFDC Query from the Editor and Test an SFDC Query in a Custom Page sections of this article.

Test an SFDC Query from the Editor

Once you have built an SFDC Query, you can test it in the query editor to ensure that data is being returned as you expect.

  1. Navigate to   > Settings > Labs.
  2. In the SFDC Query area, click Manage.
  3. In the SFDC Queries page, go to the Queries tab in the left sidebar.
  4. Find the query you want to test, and click on it to open it for edit.
  5. In the Test area:
    • Note the label which indicates what level of scoping is currently applied to the query.
    • Select the Partner and Partner User whose data you want to use as the context of the query.
  6. Click Run Test. Unifyr One runs the query, and gives guidance on success/failure, the resolved SOQL code, and query output if applicable.
  7. [Optional] Test with users from multiple different partner organizations to confirm that scoped queries correctly restrict results to each partner's own data.

Test an SFDC Query in a Custom Page

Once you have built an SFDC Query, you can view it in the partner portal using a corporate test account before publishing it to your desired partners. This is to ensure that all data is displayed correctly.

Testing is a three step process:

Build a Custom Page for your SFDC Query

Add the Custom Page to the Partner Portal

View Your SFDC Query in Your Test Partner Account

Build a Custom Page for your SFDC Query

A custom page will deliver the data from your SFDC Query to the partner portal. For information on creating a Custom Page, see Create a Custom Page.

When creating the custom page, use these guidelines:

  • Add a Dynamic Content widget to the content of your page.

  • When configuring the Dynamic Content widget, you select the type of content you want presented by the widget (by default, the widget shows the Login type). All active SFDC Queries are presented in the Select the content to use list to the right of the page when you click on the widget (they’re prefixed with SFDC Query). Choose the one you want to display.

    admin_custom_page_sfdc_query.gif

    When this widget is added to your Custom Page, it will automatically renders the appropriate data to each partner account that has access to the page.

Add the Custom Page to the Partner Portal

Add the custom page that includes the SFDC Query widget to the partner portal. For more information, see Adding Custom Pages to a Partner Portal.

When you are adding this custom page to a Partner View of the portal, you can have two options:

  • Add the page to a custom Partner View used specifically for testing purposes.

    Note

    Make sure your test partner portal account has access to the Partner View to which you are adding the custom page. Otherwise, you will not be able to see it.

  • If you don’t have a custom Partner View for testing, add the page to any of your standard views then manage the Visibility of the page so it’s only available to an internal/testing Partner Group.

View the SFDC Query in your Test Partner Account

View the custom page that includes the SFDC Query content widget in the partner portal, to make sure the data from the query is displaying correctly.

  1. Log into your test partner portal account.
  2. Navigate to the custom page in your site navigation.

  3. Review the information from your SFDC Query in the page.

    Here is an example of how query data can be displayed:

    SFDC_Query_in_partner_portal.png

    Note

    The data, columns, and exporting options available are based on two things:

    • The base code in the SFDC SOQL Query in Salesforce.
    • Any overrides you made to the base code in the Template for your query. For an example, see the Sample Template section of this article.

Get a Version History for an SFDC Query

You can get a list of versions that have been created of an SFDC Query.

  1. Navigate to   > Settings > Labs.
  2. In the SFDC Query area, click Manage.
  3. In the SFDC Queries page, go to the Queries tab in the left sidebar.
  4. Find the query you want to view, and click on it to open it for edit.
  5. Go to the Versions area. This shows a list of draft and published versions of the query, and who created them. 
  6. [Optional] Click Restore to restore a previous version.

Make the SFDC Query Available to Partners

When you have added a custom page with a SFDC Query widget to your portal site navigation, and tested the display of data in your test account, you can publish the page to your partners.

Note: This process assumes that the Active toggle for the Query is enabled. For information, see the Create an SFDC Query section of this article.

Do one of the following, depending on how you tested the page:

  • Move the custom page into the appropriate partner-facing Partner View of the site.
  • Set the Visibility of the page to make it available to the appropriate Partner Group.

Here is an example of how query data could be displayed for your partners:

SFDC_Query_in_partner_portal.png

Note

The data, columns, and exporting options available are based on two things:

  • The base code in the SFDC SOQL Query in Salesforce.
  • Any overrides you made to the base code in the Template for your query. For an example, see the Sample Template section of this article.

FAQs

Click on the + to expand the instructions for the desired task.

How do I retrieve the API Security Token from Salesforce?

For instructions on retrieving your Salesforce security token, see Salesforce help.

Which Merge Fields does Unifyr One support for an SFDC query?

Unifyr One supports the following merge fields:

Merge Field Description 
{partner.id}
 Partner ID 
{partner.name}
 Partner Name 
{partner.external_id}
 Salesforce Account ID 
{partner.sso_company_id}
 SSO Company ID 
{partner.customfieldname}

Merge fields to represent your own custom Partner Fields.

Note

The custom Partner field names must be in lower case when used as a merge field. For example, enter the custom field 2023 Commission Payments as  {partner.2023commissionpayments}.

 
{user.id}
 User ID 
{user.email}
 User Email 
{user.customfieldname}

Merge fields to represent your own custom Partner User fields.

Note

The custom Partner User field names must be in lower case when used as a merge field. For example, enter the custom field Preferred Language as  {user.preferredlanguage}.

 
{z123user.ssouserid}
 SSO User ID 
{z123client.id}
 Zift123 Client ID

Sample SFDC SOQL Query

See the sample code below, or download the Sample_SFDC_SOQL_Query.txt file attached to this article. 

SELECT Name, Owner.name, Partner_Text__c, Auto_Gen_Opportunity_ID__c, Type,
Partner__r.name,Partner__r.Zift_Partner_Id__c,
Deal_Reg_Primary_Product_Interest_Text__c, End_Customer__r.Name, CreatedDate,
CloseDate, Amount, CurrencyIsoCode, StageName, Lost_Reason__c, Won_Reason__c
FROM Opportunity

Sample Template

See the sample code below, or download the Sample_template.txt file attached to this article. 

<style>
#tableExport th, #tableExport td {
.container {
width:100% !important;
max-width: 1300px !important;
}
.samewidth{
width:100px;
}
.table.table-striped.small {
overflow: scroll;
height: 600px;
display: block;
}
table.table.table-striped.small tr th:nth-of-type(1),
table.table.table-striped.small tr td:nth-of-type(1),
table.table.table-striped.small tr th:nth-of-type(10),
table.table.table-striped.small tr td:nth-of-type(10) {
min-width: 100px !important;
}

white-space: nowrap;
}
</style>


<script>
$('#export_btn').click(function () {
var btn = $(this);
btn.button('loading');
setTimeout(function () {
btn.button('reset');
}, 2000);
});

var app = angular.module('ziftAppModule',[]);
app.filter('replaceCommas', function() {
return function(input) {
return input.replace(/,/g,'');
};
});

var angScope = getScope('ziftAppModule');
angScope.monthFilter;
angScope.yearFilter;

$(document).on("change",".month_filter",function(){
var monthName = $(this).children('option:selected').text();
if(monthName == 'Select a month'){
angScope.monthFilter = "";
$("#sfdc-query-list table th.clickable:last").click();
}
else{
filterMonth(monthName);
}
});

$(document).on("change",".year_filter",function(){
var yearVal = $(this).children('option:selected').text();
if(yearVal == 'Select a year'){
angScope.yearFilter = "";
$("#sfdc-query-list table th.clickable:last").click();
}
else{
filterYear(yearVal);
}
});

function getScope(ctrlName) {
var sel = 'html[ng-app="' + ctrlName + '"]';
return angular.element(sel).scope();
}
function filterMonth(monthName){
angScope.monthFilter = monthName;
$("#sfdc-query-list table th.clickable:last").click();
}
function filterYear(year){
angScope.yearFilter = year;
$("#sfdc-query-list table th.clickable:last").click();
}
function clearFilters(){
$(".searchField").val('');
$("select.month_filter").children("option:first").prop('selected', true);
$("select.year_filter").children("option:first").prop('selected', true);
angScope.searchText = "";
angScope.monthFilter = "";
angScope.yearFilter = "";
$("#sfdc-query-list table th.clickable:last").click();
}
angScope.exportResults2 = function(data) {
const blob = new Blob(["\ufeff", data], {
type: 'text/csv;charset=utf-8'
});
const link = document.createElement('a');
link.download = 'export.csv';
link.href = window.URL.createObjectURL(blob);;
link.click();
}

angScope.exportTable2 = function(tableSelector) {
var table = angular.element(tableSelector)[0];
var csvString = '';
if (table) {
for (var i = 0; i < table.rows.length; i++) {
var rowData = table.rows[i].cells;
for (var j = 0; j < rowData.length; j++) {
var text = rowData[j].innerText || rowData[j].textContent;
text = text.replace(/"/g, '\\\"');

if (Date.parse(text) && text.split(/[\-\/]+/).length == 3) {
text = new Date(text+' 00:00:00.000Z').toISOString().substring(0,10);
}
else {
text = '"' + text + '"'; // wrap in quotes so commas in the string do not lead to data in wrong cols
}

csvString = csvString + text + ",";
}
csvString = csvString.substring(0, csvString.length - 1);
csvString = csvString + "\n";
}
csvString = csvString.substring(0, csvString.length - 1);
}
return angScope.exportResults2(csvString);
}
</script>

<div id="sfdc-query-list" class="row list-view entrust-table">
<div class="col-md-12">
<div class="row zift-header">
<div class="col-sm-8">
<h2>
Deal Registration: Opportunity Details
</h2>
</div>
</div>

<div class="row">

<div class="col col-md-1 text-right" >
<a ng-click="exportTable2('#tableExport');" download='DealRegOppDetails.csv' class="btn btn-default" data-loading-text="<i class='fa fa-circle-o-notch fa-spin'></i>" id="export_btn"> Export to CSV</a>
</div>
</div>

<div class="row">
<div>
<div class="row zift-header">
<h3>{{ r.name | i18n }}</h3>
</div>
<table class="table table-striped small" id="tableExport">
<thead>
<th>{{ 'Created Date' | i18n }}</th>
<th>{{ 'Entrust Sales Rep' | i18n }}</th>
<th>{{ 'Account' | i18n }}</th>
<th>{{ 'Opportunity ID' | i18n }}</th>
<th>{{ 'Primary Product Interest' | i18n }}</th>
<th>{{ 'End Customer' | i18n }}</th>
<th>{{ 'Amount' | i18n }}</th>
<th>{{ 'Currency' | i18n }}</th>
<th>{{ 'Stage' | i18n }}</th>
<th>{{ 'Close Date' | i18n }}</th>
<th class="samewidth">{{ 'Lost Reason' | i18n }}</th>
<th class="samewidth">{{ 'Won Reason' | i18n }}</th>
</thead>
<tbody>
<tr ng-repeat="r in queryResults.list">
<td class="text-right">{{ r.CreatedDate | date:'MM-dd-yyyy'}}</td>
<td class="text-right">{{ r.Owner.Name }}</td>
<td class="text-right">{{ r.Partner_Text__c}}</td>
<td class="text-right">{{ r.Auto_Gen_Opportunity_ID__c }}</td>
<td class="text-right">{{ r.Deal_Reg_Primary_Product_Interest_Text__c}}</td>
<td class="text-right">{{ r.End_Customer__r.Name }}</td>
<td class="text-right">{{ r.Amount | number}}</td>
<td class="text-right">{{ r.CurrencyIsoCode }}</td>
<td class="text-right">{{ r.StageName }}</td>
<td class="text-right">{{ r.CloseDate | date:'MM-dd-yyyy' }}</td>
<td class="text-right">{{ r.Lost_Reason__c }}</td>
<td class="text-right">{{ r.Won_Reason__c }}</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.