Skip to main content

FarseerClient

The main class for interacting with the Farseer API. Extends RawFarseerClient (auto-generated) with high-level convenience methods.

Constructor​

new FarseerClient()
new FarseerClient(tenantId: string)
new FarseerClient(tenantId: string, apiKey: string)
new FarseerClient(tenantId: string, apiKey: string, basePath: string)
new FarseerClient(config: ConfigurationParameters)

Parameters:

ParameterTypeRequiredDescription
tenantIdstringNoFarseer tenant identifier. Falls back to TENANT_ID env var
apiKeystringNoAPI key for authentication. Falls back to FARSEER_API_KEY env var
basePathstringNoServer URL. Falls back to FARSEER_URL env var
configConfigurationParametersNoFull configuration object

Example:

// Auto-configuration from environment variables
const client = new FarseerClient();

// Manual configuration
const client = new FarseerClient('my-tenant', 'my-api-key', 'https://app.farseer.io');

// Advanced configuration
const client = new FarseerClient({
    basePath: 'https://app.farseer.io/api/v3',
    headers: { 'X-TENANT-ID': 'my-tenant', 'X-API-KEY': 'my-api-key' },
});

Tag Management​

initTagMap()​

Loads all variables, dimension tables, and dimension members into an in-memory lookup map. Must be called before using tag-related methods.

initTagMap(): Promise<TagMaps>

Returns: TagMaps object with lookup maps.

await client.initTagMap();
// Now you can use getVariable(), getDimensionTable(), etc.

getVariable(name)​

Retrieves a variable entity by name.

getVariable(name: string): Promise<TagRepresentation>
ParameterTypeRequiredDescription
namestringYesVariable name (case-sensitive)

Returns: TagRepresentation with variable metadata.

const revenue = await client.getVariable('Revenue');
console.log(revenue.id);              // 42
console.log(revenue.type);            // "ACCOUNT"
console.log(revenue.dataType);        // "Decimal"
console.log(revenue.expression);      // Formula expression
console.log(revenue.dimensionTagIds); // [10, 11, 12]

getDimensionTable(name)​

Retrieves a dimension table by name.

getDimensionTable(name: string): Promise<TagRepresentation>
ParameterTypeRequiredDescription
namestringYesDimension table name
const products = await client.getDimensionTable('Products');
console.log(products.id);   // 10
console.log(products.type);  // "TABLE"

getDimensionMember(dimensionTableName, dimensionMemberName)​

Retrieves a specific dimension member.

getDimensionMember(dimensionTableName: string, dimensionMemberName: string): Promise<TagRepresentation>
ParameterTypeRequiredDescription
dimensionTableNamestringYesParent dimension table name
dimensionMemberNamestringYesMember name
const plan = await client.getDimensionMember('Versions', 'Plan');
console.log(plan.id);   // 27
console.log(plan.type);  // "DIMENSION"

getDimensionMembersForTable(dimensionTableName)​

Returns all members of a dimension table.

getDimensionMembersForTable(dimensionTableName: string): Promise<TagRepresentation[]>
const versions = await client.getDimensionMembersForTable('Versions');
versions.forEach(v => console.log(v.name)); // "Actual", "Plan", "Budget"

resolveDimensionMember(member)​

Resolves a DimensionMemberType (table name + member name pair) or an existing TagRepresentation to a TagRepresentation. If the input already has an id, it is returned as-is; otherwise getDimensionMember is called.

resolveDimensionMember(member: DimensionMemberType | TagRepresentation): Promise<TagRepresentation>
// From a name pair
const tag = await client.resolveDimensionMember({ tableName: 'Versions', memberName: 'Plan' });

// Already resolved — returned as-is
const same = await client.resolveDimensionMember(tag);

filterDimensionMembers(dimensionMembers, filterDimensionMembers)​

Filters dimension members by connected members (OR logic - matches any).

filterDimensionMembers(
    dimensionMembers: (DimensionMemberType | TagRepresentation)[],
    filterDimensionMembers: (DimensionMemberType | TagRepresentation)[]
): Promise<TagRepresentation[]>

filterDimensionMembersByAll(dimensionMembers, filterDimensionMembers)​

Filters dimension members by connected members (AND logic - matches all).

filterDimensionMembersByAll(
    dimensionMembers: (DimensionMemberType | TagRepresentation)[],
    filterDimensionMembers: (DimensionMemberType | TagRepresentation)[]
): Promise<TagRepresentation[]>

getDimensionMemberAncestors(member, depth?)​

Returns ancestor members in the hierarchy.

getDimensionMemberAncestors(
    member: TagRepresentation,
    depth?: number
): Promise<TagRepresentation[]>

getDimensionMemberDescendants(member, depth?)​

Returns descendant members in the hierarchy.

getDimensionMemberDescendants(
    member: TagRepresentation,
    depth?: number
): Promise<TagRepresentation[]>

clearTagMap()​

Clears the in-memory tag map. Call initTagMap() again to reload.

client.clearTagMap();

Folder Navigation​

getItemByPath(path)​

Navigates the folder structure and retrieves an item by path.

getItemByPath(path: string[]): Promise<FolderItemRepresentation>
ParameterTypeRequiredDescription
pathstring[]YesArray of folder/file names from root
const file = await client.getItemByPath(['Finance', 'Reports', 'data.xlsx']);
console.log(file.id);        // 123
console.log(file.reference);  // UUID reference for file download

findItemNode(itemNodeName, itemNodeType)​

Finds an item node by name and type.

findItemNode(itemNodeName: string, itemNodeType: FolderItemType): Promise<FolderItemRepresentation>
const folder = await client.findItemNode('Reports', FolderItemType.Folder);

getFolderItems(folderInfo)​

Gets all items in a folder.

getFolderItems(folderName: string): Promise<FolderItemRepresentation[]>
getFolderItems(folderId: number): Promise<FolderItemRepresentation[]>

getFolderItem(folderInfo, itemName)​

Gets a specific item in a folder by name.

getFolderItem(folderName: string, itemName: string): Promise<FolderItemRepresentation>
getFolderItem(folderId: number, itemName: string): Promise<FolderItemRepresentation>

Import Operations​

createImportJob(config)​

Creates an import job with simplified column configuration.

createImportJob(config: {
    title: string;
    columns?: ImportMetadataColumn[];
    metadata?: ImportJobMetadata;
    description?: string;
    labels?: string[];
}): Promise<ImportActions>
ParameterTypeRequiredDescription
titlestringYesImport job title
columnsImportMetadataColumn[]NoSimplified column definitions (recommended)
metadataImportJobMetadataNoFull metadata (advanced, alternative to columns)
descriptionstringNoJob description
labelsstring[]NoLabels for job identification and undoPrevious()

Column types:

type ImportMetadataColumn =
    | { type: 'DIMENSION_TABLE'; dimensionTableName: string; columnName?: string }
    | { type: 'VARIABLE'; variableName: string; dimensionsNames?: string[]; columnName?: string }
    | { type: 'DATE'; dateFormat: string; columnName?: string }
    | { type: 'DESCRIPTION'; columnName?: string }
    | { type: 'CUSTOM'; columnName: string }
    | { type: 'NONE'; columnName?: string };

Returns: ImportActions object.

const importJob = await client.createImportJob({
    title: 'Revenue Import Q1',
    columns: [
        { type: 'DIMENSION_TABLE', dimensionTableName: 'Products' },
        { type: 'DIMENSION_TABLE', dimensionTableName: 'Years' },
        { type: 'DIMENSION_TABLE', dimensionTableName: 'Months' },
        { type: 'VARIABLE', variableName: 'Revenue' },
    ],
    labels: ['auto', 'revenue', 'Q1-2024']
});

await importJob.addRows([
    ['Product A', 'Y2024', 'January', 100000],
    ['Product A', 'Y2024', 'February', 120000],
]);
await importJob.flushRows();
await importJob.undoPrevious();
await importJob.commit();

buildImportJobMetadata(columns)​

Builds import job metadata from simplified column definitions. Used internally by createImportJob.

buildImportJobMetadata(columns: ImportMetadataColumn[]): Promise<ImportJobMetadata>

File Operations​

createOrUpdateFarseerFile(fileInfo, data)​

Creates or updates a file in Farseer. Supports two overloads:

// Overload 1: Create or update by name and folder ID
createOrUpdateFarseerFile(
    fileInfo: { name: string; folderId: number },
    data: Buffer | Blob
): Promise<void>

// Overload 2: Update an existing folder item
createOrUpdateFarseerFile(
    fileItem: FolderItemRepresentation,
    data: Buffer | Blob
): Promise<void>

createExcelWorkbookFromFarseerFile(folderInfo, fileName)​

Downloads a Farseer file and returns it as an ExcelJS workbook.

createExcelWorkbookFromFarseerFile(
    folderInfo: string | number,
    fileName: string
): Promise<exceljs.Workbook>

readExcelWorksheetsFromFarseerFile(folderInfo, fileName, readHiddenSheets?)​

Reads Excel worksheets as parsed data.

readExcelWorksheetsFromFarseerFile(
    folderInfo: string | number,
    fileName: string,
    readHiddenSheets?: boolean
): Promise<ParsedWorksheetData[]>
ParameterTypeRequiredDescription
folderInfostring | numberYesFolder name or ID
fileNamestringYesFile name
readHiddenSheetsbooleanNoWhen true, includes hidden worksheets in the result

Data Operations​

evaluatorExport(exportConfiguration)​

Exports data using the evaluator engine. Returns a Blob of CSV or JSON data.

evaluatorExport(exportConfiguration: ExportConfiguration): Promise<Blob>

See ExportConfiguration for the configuration format.

copyAllCells(config)​

Copies all cells matching dimension mappings with optional filters. Resolves names to IDs automatically.

copyAllCells(config: {
    mappings: { dimensionTable: string; from: string; to: string }[];
    filters?: Record<string, string[]>;
    variables?: string[];
    skipVariables?: string[];
    skipZeros?: boolean;
    clearData?: boolean;
}): Promise<void>
ParameterTypeRequiredDescription
mappings{ dimensionTable, from, to }[]YesDimension member mappings (source → target)
filtersRecord<string, string[]>NoFilter by dimension table name → member names
variablesstring[]NoOnly copy these variables (by name)
skipVariablesstring[]NoSkip these variables (by name)
skipZerosbooleanNoSkip cells with zero values
clearDatabooleanNoClear target cells before copying
await client.copyAllCells({
    mappings: [
        { dimensionTable: 'Versions', from: 'Actual', to: 'Plan' },
    ],
    filters: { 'Years': ['Y2024'] },
    skipZeros: true,
});

copyCells(config)​

Copies cells from a source variable or formula to a target variable. Supports two overloads:

// Overload 1: Copy from a source variable with optional filters
copyCells(config: {
    sourceVariable: string;
    sourceFilters?: Record<string, string>;
    targetVariable: string;
    targetFilters?: Record<string, string>;
}): Promise<void>

// Overload 2: Copy from an evaluator formula
copyCells(config: {
    sourceFormula: string;
    targetVariable: string;
    targetFilters?: Record<string, string>;
}): Promise<void>
// Copy variable to variable
await client.copyCells({
    sourceVariable: 'Revenue',
    sourceFilters: { 'Versions': 'Actual' },
    targetVariable: 'Revenue',
    targetFilters: { 'Versions': 'Plan' },
});

// Copy formula result to variable
await client.copyCells({
    sourceFormula: 'sum("Revenue", "Y2024")',
    targetVariable: 'Revenue Target',
    targetFilters: { 'Versions': 'Plan' },
});

lockCells(lockItems)​

Deprecated

This method throws an error. Locks have been upgraded — use client.settings.getGlobalLocks() and client.settings.setGlobalLocks(lockRules) instead.

lockCells(lockItems: FarseerLockItem[]): Promise<void>

unlockCells(lockItems)​

Deprecated

This method throws an error. Locks have been upgraded — use client.settings.getGlobalLocks() and client.settings.setGlobalLocks(lockRules) instead.

unlockCells(lockItems: FarseerLockItem[]): Promise<void>

warmupCache(timeoutMinutes?)​

Warms up the server-side cache.

warmupCache(timeoutMinutes?: number): Promise<void>

Utility Methods​

getInternalTagType(tagName)​

Returns the internal tag type for built-in dimension tables (Years, Quarters, Half Years, Months, Versions, Year to Date). Returns null for custom dimension tables.

getInternalTagType(tagName: string): InternalTagType | null
client.getInternalTagType('Years');    // InternalTagType.Year
client.getInternalTagType('Months');   // InternalTagType.Month
client.getInternalTagType('Products'); // null (custom table)

mapEntityToTag(entity, parentEntity?)​

Maps a raw Entity (from the REST API) to a TagRepresentation. Used internally by initTagMap.

mapEntityToTag(entity: Entity, parentEntity?: Entity): TagRepresentation

Generated API Modules​

The client exposes all auto-generated API modules as properties. Each module corresponds to a group of REST endpoints:

ModulePurposeExample
client.usersUser managementclient.users.list()
client.userGroupsUser group managementclient.userGroups.list()
client.entitiesEntity operationsclient.entities.getMany()
client.evaluatorFormula evaluationclient.evaluator.evaluate()
client.exportData exportclient.export.exportFormula()
client.importJobsImport job operationsclient.importJobs.list()
client.cellsCell operationsclient.cells.calculateOnDemandCells()
client.foldersFolder managementclient.folders.list()
client.farseerFilesFile operationsclient.farseerFiles.get()
client.sheetsSheet managementclient.sheets.list()
client.sheetRowsSheet row operationsclient.sheetRows.list()
client.dashboardsDashboard managementclient.dashboards.list()
client.sharesSharing/access controlclient.shares.list()
client.permissionsPermission managementclient.permissions.search()
client.modelModel operationsclient.model.load()
client.versionsVersion managementclient.versions.list()
client.timePointsTime point operationsclient.timePoints.list()
client.labelsLabel managementclient.labels.list()
client.assignmentsAssignment workflowsclient.assignments.list()
client.assignmentLabelsAssignment labelsclient.assignmentLabels.list()
client.chatAI chatclient.chat.askAI()
client.messageThreadsMessagingclient.messageThreads.list()
client.remoteJobsRemote job executionclient.remoteJobs.list()
client.remoteJobRunsRemote job runsclient.remoteJobRuns.list()
client.forecastJobsForecast operationsclient.forecastJobs.search()
client.auditLogsAudit trailclient.auditLogs.search()
client.settingsSystem settingsclient.settings.list()
client.apiKeysAPI key managementclient.apiKeys.create()
client.exportConfigurationsExport configsclient.exportConfigurations.list()
client.maintenanceSystem maintenanceclient.maintenance.run()
client.gatewayGateway operationsclient.gateway.run()
client.engineEngine operationsclient.engine.checkExpression()
client.backpropBack-propagation operationsclient.backprop.*
client.customerSupportCustomer supportclient.customerSupport.*
client.keycloakConfigurationsSSO/Keycloak configclient.keycloakConfigurations.*
client.overseerSystem monitoringclient.overseer.*
client.userActivityUser activity trackingclient.userActivity.*

Static Properties​

FarseerClient.IMPORT_JOB_ROW_BATCH_SIZE = 500; // Default batch size for import rows