Find and Selection

•

Version: 9.2

• 11 minutes to read

SuperOffice Find is a unification of the Find dialog and Selections: two legacy approaches to search for specific information. SuperOffice provides new APIs to perform searches, used by both Find and Selections, and for you to easily implement the same search capability for integrations.

This section covers the terms and concepts needed to understand how to programmatically work with Find just like in SuperOffice.

Note

The API details provided apply to SuperOffice v.9.2 and higher. SOAP API access via the Services88 endpoints, therefore Online Apps must request Services88 to use this API.

Getting started

The way a search begins today is by clicking the Find option.

When clicked, the Find panel appears and all of the primary business entities are listed on the page. By default, one dynamic selection is created and maintained per user, per entity. When a user selects one of the Find [Entity] links, SuperOffice retrieves the previously-saved dynamic selection criteria for the selected entity, or loads the default criteria for that entity, and populates the Selection search find panel.

Find Panel

Alternatively, a pre-defined typical search option is chosen from an entity Typical searches drop-down menu. When selected, the pre-defined typical search criteria populate the Selection search find panel.

Selection search panel

Each search is functionally equivalent to a dynamic selection. Once the search criteria have been set and saved, the Find becomes a Selection and is available for future reference.

The remainder of this section will highlight the key types and methods used to construct, persist, and invoke a selection.

SelectionEntity

A SelectionEntity contains only a handful of properties, most of which appear in the Selection details tab, and have the following considerations:

Selection entity
Type of selection
Owner
Category
Who can see it.
Description

The corresponding properties are:

Name	Description
Name	Selection name.
MainProviderName	Name of the archive provider responsible for populating the selection.
SelectionType	Defines whether this is a dynamic, static, or combined selection.
Owner	The associate responsible for the selection.
SelectionCategory	List item that describes the type of selection.
VisibleFor	Define the user or groups with access rights to this selection.
Description	A short description of the selection list.

Get a selection entity

GET /api/v1/Selection/18 HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

POST /api/v1/Agents/Selection/GetSelectionEntity?selectionEntityId=18 HTTP/1.1
Authorization: Bearer {access_token}
Accept: application/json; charset=utf-8
Accept-Language: en

// setup access credentials
var authorization = new AuthorizationAccessToken("{access_token}", OnlineEnvironment.SOD);
var options = new WebApiOptions("https://sod.superoffice.com/Cust12345/api", authorization);

int selectionId = 18;
// perform the request
var selectionAgent = new SelectionAgent(options);
SelectionEntity selectionEntity = await selectionAgent.GetSelectionEntity(selectionId);

Note

It is important to not hard-code the selection provider names. Future support may include selections of more entities.

Selection criteria

Archive provider columns are the core of selection. Just like a SQL SELECT statement, where there are any number of select fields and any number of WHERE clause criteria, selections use archive provider columns as select fields and criteria.

Selection criteria are established using criteria groups.

CriteriaGroups contain an array of ArchiveRestrictionInfo. This array is encapsulated in an ArchiveRestrictionGroup and referred to as one CriteriaGroup.

Each ArchiveRestrictionInfo in an ArchiveRestrictionGroup is implicitly joined by an AND operator.
Each ArchiveRestrictionGroup is implicitly joined by an OR operator.

The grouping and use of the operator as such means it's simple to define, maintain and comprehend how groups of criteria are applied to selection search routines.

Example

Take the following SQL, for example:

SELECT firstName, lastName 
FROM CONTACT AS C
WHERE (C.name LIKE 'Super%' AND C.business_idx = 2) 
   OR (C.name LIKE 'Duper%' AND C.category_idx = 12)

The first WHERE criteria, (C.name LIKE 'Super%' AND C.business_idx = 2), is a criteria group, comprised of 2 distinct criteria. To build the equivalent into an ArchiveRestrictionGroup, it looks like this:

var criteriaGroup = new ArchiveRestrictionGroup()
{
    Name = "0",
    Rank = 0,
    Description = "Hidden Description",
    Restrictions = new []
    {
        new ArchiveRestrictionInfo()
        {
            Name = "name",
            Operator = "begins",
            Values = new[] { "Super" },
            IsActive = true,
            ColumnInfo = new ArchiveColumnInfo()
            {
                Name = "name",
                RestrictionType = "stringorPK",
                RestrictionListName = "locateContact_new",
                //... left out for brevity
            },
            InterOperator = InterRestrictionOperator.And
        },
        new ArchiveRestrictionInfo()
        {
            Name = "name",
            Operator = "begins",
            Values = new[] { "Duper" },
            IsActive = true,
            ColumnInfo = new ArchiveColumnInfo()
            {
                Name = "name",
                RestrictionType = "stringorPK",
                RestrictionListName = "locateContact_new",
                //... left out for brevity
            },
            InterOperator = InterRestrictionOperator.And
        }
    }
};

As seen in the C# example above, the Name and Rank share the same numerical value, represent the order they appear in SuperOffice. The Name and Rank for the next ArchiveRestrictionGroup in the array are 1, and any subsequent group would increment one more than the one before it.

Working with selections

There are a couple of different ways to create a selection. While you can manually craft a SelectionEntity, save it, and then populate the CriteriaGroups, the recommended approach is to use the APIs to assembly the required information:

Get the available entities.
Get the SelectionForFind to get the archive provider name or selection ID.
Create default selection.
Get the available display columns for the archive provider
Get the available restriction columns for the archive provider
Get the available entities for the archive provider

Below, we address how to create and save a selection. For more details, check out our tutorial on how to search using Find Selections.

Get the Find entities

The Find page dynamically displays all entities that support the new Find system.

Note

Available entities depend on the current user's license.

Learn how to do it in code.

Get the SelectionForFind type

After getting the available entities, you can use the entity name to get the appropriate SelectionForFind result, which not only specifies the correct archive provider name for this search type, it specifies the default selection ID associated with the entity type. This ID can then be used to get the default criteria groups for that selection type.

The selection ID indicates the associates personalized dynamic selection primary key, containing a default list of criteria used to pre-populate a new selection of this entity type. This is updated each time a user creates a new dynamic selection.

Learn how to do it in code.

Note

All Find Selections use an archive provider whose name ends with the "V2" suffix, for example, AppointmentDynamicSelectionV2 and ContactPersonDynamicSelectionV2.

Create a Selection

Once you have the SelectionForFind, use the MainArchiveProvider to set the Selection property of the same name.

GET /api/v1/Selection/default HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

POST /api/v1/Agents/Selection/CreateDefaultSelectionEntity HTTP/1.1
Authorization: Bearer {access_token}
Accept: application/json; charset=utf-8
Accept-Language: en

// setup access credentials
var authorization = new AuthorizationAccessToken("{access_token}", OnlineEnvironment.SOD);
var options = new WebApiOptions("https://sod.superoffice.com/Cust12345/api", authorization);

int selectionId = 18;
// perform the request
var selectionAgent = new SelectionAgent(options);
SelectionEntity selectionEntity = await selectionAgent.CreateDefaultSelectionEntity();

Save the SelectionEntity

Only a subset of selection properties must be set to save a selection. The main properties are Name, MainProviderName, and SelectionCategory.

POST /api/v1/Selection HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

{
  "Description": "Testing Selections (Description)",
  "Postit": "",
  "SelectionCategory": {
    "Id": 2,
  },
  "IncludePerson": 0,
  "Name": "Selections from API (Name)",
  "SelectionType": "Dynamic",
  "CompanyUnique": false,
  "TargetTableNumber": 5,
  "TargetTableName": "contact",
  "Completed": false,
  "LeftSelectionId": 0,
  "RightSelectionId": 0,
  "SelectionUnionType": "Unknown",
  "MainProviderName": "ContactPersonDynamicSelectionV2",
  "ShadowProviderName": "",
  "MainHeading": "[SR_SELECTION_DYNAMICSELECTION_OF] [SR_COMPANY_AND_PERSON] (MainHeading)",
  "MemberTabHeading": "[SR_COMPANY_AND_PERSON] (MemberTabeHeading)",
  "VisibleFor": [
    {
      "VisibleId": 0,
      "Visibility": "All",
    }
  ]
}

POST /api/v1/Agents/Selection/SaveSelectionEntity HTTP/1.1
Authorization: Bearer {access_token}
Accept: application/json; charset=utf-8
Accept-Language: en

{
  "Description": "Testing Selections (Description)",
  "Postit": "",
  "SelectionCategory": {
    "Id": 2,
  },
  "IncludePerson": 0,
  "Name": "Selections from API (Name)",
  "SelectionType": "Dynamic",
  "CompanyUnique": false,
  "TargetTableNumber": 5,
  "TargetTableName": "contact",
  "Completed": false,
  "LeftSelectionId": 0,
  "RightSelectionId": 0,
  "SelectionUnionType": "Unknown",
  "MainProviderName": "ContactPersonDynamicSelectionV2",
  "ShadowProviderName": "",
  "MainHeading": "[SR_SELECTION_DYNAMICSELECTION_OF] [SR_COMPANY_AND_PERSON] (MainHeading)",
  "MemberTabHeading": "[SR_COMPANY_AND_PERSON] (MemberTabeHeading)",
  "VisibleFor": [
    {
      "VisibleId": 0,
      "Visibility": "All",
    }
  ]
}

// setup access credentials
var authorization = new AuthorizationAccessToken("{access_token}", OnlineEnvironment.SOD);
var options = new WebApiOptions("https://sod.superoffice.com/Cust12345/api", authorization);

var selectionAgent = new SelectionAgent(config);
selectionEntity = await selectionAgent.CreateDefaultSelectionEntityAsync();
selectionEntity.Name = "Selections from API (Name)";
selectionEntity.Description = "Testing Selections (Description)";
selectionEntity.MailingsProviderName = "ContactPersonDynamicSelectionV2";
selectionEntity.SelectionCategory = new SelectionCategory() { Id = 2 };
selectionEntity.SelectionType = SelectionType.Dynamic;
selectionEntity.VisibleFor = new[] 
{
    new VisibleFor()
    {
        Visibility = Visibility.All,
        VisibleId = 0
    }
};

selectionEntity = await selectionAgent.SaveSelectionEntityAsync(selectionEntity);

Note

When saving a selection, the default setting for populating the VisibleFor property looks at the user preferences. Section Defaults and key DefaultSelectionVisibleFor.

The default value is 0 (All). Other options: 1 (Associate); 2 (Group). See the default preferences in Settings and maintenance for Visibility for selections.