The Search Client API allows for any Finsemble window to act as a search provider or query against the registered providers. Finsemble comes prepackaged with two providers:Installed Components and Installed Workspaces.

Registering a search provider

The provider object is the search result item. When you register a search provider, you're expected to provide at minimum a name and searchCallback. The name will allow you to identify which provider your search results came from. We recommended that you keep all providers inside of a service so they are available throughout the lifetime of your Finsemble application.

		name: "My Search Provider", // The name of the provider
		searchCallback: providerSearchFunction, // A function called when a search is initialized
		itemActionCallback: searchResultActionCallback, // (optional) A function that is called when an item action is fired
		providerActionTitle: "My Provider action title", // (optional) A function that is called when a provider action is fired
		providerActionCallback: providerActionCallback, // (optional) The title of the provider action
	function (err) {
		console.log("Registration succeeded");

Receiving a search request

Your searchCallback is called when a search is initiated that includes your provider. The arguments for searchCallback are params and a callback. Currently, params only has the one parameter: text. text is the string to search against. When you return results from your search provider you should return an array of resultItems:

function providerSearchFunction(params, callback) {

	var results = [resultItems];
	callback(null,results); // The first argument is an error;

//Your return results to the callback should be an array of the following:
	name: resultName, // This should be the value you want displayed
	score: resultScore, // This is used to help order search results from multiple providers
	type: "Application", // The type of data your result returns
	description: "Your description here",
	actions: [{ name: "Spawn" }], // Actions can be an array of actions
	tags: [] // This can be used for adding additional identifying information to your result

The resultScore should be a number between 0 and 100, with 0 being a complete match.

The type can be anything you want. However, "Application" and "Workspace" are reserved for Finsemble components and workspaces and should only be used for those data types.

Handling actions

There are two types of actions that a provider can handle: item action and provider action.

Item actions

Item actions sit with each result you provide and allow your provider to control what happens when that action is invoked. When an item action is triggered, the Search Client invokes your itemActionCallback in the provider. You get an object with two parameters with this callback: item and action. item is the search result item that triggered the action. action is the item in your search result actions array that was triggered (actions:[{ name: "Spawn" }]).

function searchResultActionCallback(params) {
	params is equal to 

	// Do something with the action here

Provider action

The provider action is an optional singular parameter that is at the provider level. This is any action you want to occur at the global level for the provider. An example would be if you had an app store provider that had an option for opening an app store component at the provider level. To receive a provider action you must pass in a function when you register through the providerActionCallback option. You may also provide providerActionTitle to help with displaying your action.

function providerActionCallback() {
	// Do something with the action here

Querying search providers


You call to query against a search provider.

This method takes an object with a property of text and a function that is called as results are returned. This returns a combined array of all results returned from each provider, which means it can be called many times per search.{text:"searchTerm",function(err, response){
	console.log("Array of providers and their responses",response);
// This is the repsonse.
	data:[results], // This is the array of results
		channel:providerChannel,// This is the channel used by the client to communicate back to the provider
		providerActionCallback:Boolean,// This tells us if the provider has an action at the provider level
		providerActionTitle:"Your action title",// The title to display for the action
	searchId:"UIUD",// This is used internally to identify results returned from each provider


invokeItemAction allows you to send an event back to the search provider with the item and action you'd like to trigger. Actions are defined inside of each result item: item.actions.


Like invokeItemAction, invokeProviderAction allows you to call an action at the provider level. This action is optional and up to the provider to implement. You should pass in the provider object that is returned with your search results.

check   The Search API allows for any Finsemble window to act as a search provider or query against the registered providers.

Further reading

Further details of the API can be found in Search Client API.