eLabSDK2.Inventory.Sample

Hierarchy

Inventory

↳ Sample

↳↳ SampleDetail

↳↳ SampleList

↳↳ SeriesDetail

Methods

displaySampleQuantity

Static displaySampleQuantity(quantity): string

Generate a human-readable display string for sample quantity.

This parses a quantity object and generates a formatted display string suitable
for showing in the UI. The format varies based on whether threshold alerts are enabled:

Without threshold: Shows just the amount and unit (e.g., "50 mL")
With threshold: Shows current amount, full capacity, and percentage remaining (e.g., "30 mL of 50 mL available (60%)")
If no quantity is specified or unit is 'Nothing', returns 'Unspecified'

Parameters

Name	Type	Description
`quantity`	`QuantityInterface`	The quantity object containing amount, unit, threshold, and capacity data.

Returns

string

A formatted string displaying the sample quantity in a user-friendly format.

Example

// Display quantity without threshold
const quantity = {
  amount: 500,
  calculationFactor: 10,
  unitShort: 'mL',
  displayUnit: 'Milliliters',
  thresholdAlertEnabled: false
};
const display = eLabSDK2.Inventory.Sample.displaySampleQuantity(quantity);
console.log(display); // Output: "50 mL"

Example

// Display quantity with threshold and capacity
const quantity = {
  amount: 300,
  fullAmount: 500,
  calculationFactor: 10,
  unitShort: 'mL',
  displayUnit: 'Milliliters',
  thresholdAlertEnabled: true,
  thresholdPercentage: 20
};
const display = eLabSDK2.Inventory.Sample.displaySampleQuantity(quantity);
console.log(display); // Output: "30 mL of 50 mL available (60.00%)"

Example

// Display unspecified quantity
const quantity = { displayUnit: 'Nothing' };
const display = eLabSDK2.Inventory.Sample.displaySampleQuantity(quantity);
console.log(display); // Output: "Unspecified"

displaySampleQuantityThreshold

Static displaySampleQuantityThreshold(quantity): string | void

Generate a human-readable display string for sample quantity threshold.

This calculates and formats the threshold amount at which alerts should be triggered
for a sample. The threshold is displayed as both an absolute amount and a percentage
of the full capacity. Returns undefined if no full amount is specified for the sample.

Parameters

Name	Type	Description
`quantity`	`QuantityInterface`	The quantity object containing full amount, threshold percentage, unit, and calculation factor.

Returns

string | void

A formatted string showing the threshold amount and percentage (e.g., "10 mL (20%)"), or undefined if fullAmount is not set.

Example

// Display threshold for a sample
const quantity = {
  fullAmount: 500,
  calculationFactor: 10,
  unitShort: 'mL',
  thresholdPercentage: 20
};
const threshold = eLabSDK2.Inventory.Sample.displaySampleQuantityThreshold(quantity);
console.log(threshold); // Output: "10 mL (20%)"

Example

// Show threshold in UI
const quantity = await eLabSDK2.Inventory.Sample.getSampleQuantity(12345);
const thresholdDisplay = eLabSDK2.Inventory.Sample.displaySampleQuantityThreshold(quantity);
if (thresholdDisplay) {
  console.log(`Alert threshold: ${thresholdDisplay}`);
} else {
  console.log('No threshold configured');
}

getSampleByID

Static getSampleByID(sampleID, filter?): Promise<SampleDetail>

Fetch complete sample data by sample ID.

This retrieves all information for a specific sample from the server, including
basic sample data, metadata, location, quantity information, and any other fields
specified in the filter's expand options. Use this when you need detailed information
about a specific sample.

Parameters

Name	Type	Description
`sampleID`	`number`	The unique identifier of the sample to fetch.
`filter?`	`Object`	Optional filter object to control what data is included. Use the expand property to include related data (e.g., {expand: ['quantity', 'meta', 'location']}).

Returns

Promise<SampleDetail>

A Promise that resolves to a SampleDetail object containing all the sample's data.

Example

// Fetch basic sample information
const sample = await eLabSDK2.Inventory.Sample.getSampleByID(12345);
console.log(sample.name); // Output: Sample name
console.log(sample.sampleTypeID); // Output: 5

Example

// Fetch sample with expanded quantity and meta information
const sample = await eLabSDK2.Inventory.Sample.getSampleByID(12345, {
  expand: ['quantity', 'meta', 'location', 'parent']
});
console.log(sample.quantity?.amount); // Quantity details
console.log(sample.meta); // Sample metadata fields
console.log(sample.storageLayerName); // Storage location

getSampleQuantity

Static getSampleQuantity(sampleID): Promise<QuantityInterface>

Fetch the quantity data of a sample by its sample ID.

This retrieves detailed quantity information for a specific sample, including
current amount, unit of measurement, threshold settings, and capacity information.
Use this when you need to check or display sample quantity without fetching
the complete sample data.

Parameters

Name	Type	Description
`sampleID`	`number`	The unique identifier of the sample whose quantity data you want to fetch.

Returns

Promise<QuantityInterface>

A Promise that resolves to a QuantityInterface object containing all quantity-related data including amount, unit, thresholds, and display settings.

Example

// Get quantity information for a sample
const quantity = await eLabSDK2.Inventory.Sample.getSampleQuantity(12345);
console.log(`Amount: ${quantity.amount} ${quantity.unitShort}`);
console.log(`Full capacity: ${quantity.fullAmount}`);
console.log(`Threshold enabled: ${quantity.thresholdAlertEnabled}`);

Example

// Check if sample is below threshold
const quantity = await eLabSDK2.Inventory.Sample.getSampleQuantity(12345);
if (quantity.thresholdAlertEnabled) {
  const percentRemaining = (quantity.amount / quantity.fullAmount) * 100;
  if (percentRemaining < quantity.thresholdPercentage) {
    console.log('Warning: Sample is below threshold!');
  }
}

getSampleTypeSpecificationByID

Static getSampleTypeSpecificationByID(sampleTypeID, sampleTypeSpecificationID, filter?): Promise<any>

Fetch a specific metadata field specification for a sample type.

This retrieves detailed information about a single metadata field (specification)
that is defined for a particular sample type. Specifications define the structure
and validation rules for sample metadata fields. Use this to understand the
configuration of a specific metadata field, including its type, constraints,
and display options.

Parameters

Name	Type	Description
`sampleTypeID`	`number`	The ID of the sample type that contains the specification.
`sampleTypeSpecificationID`	`number`	The unique ID of the metadata field specification to fetch.
`filter?`	`GetSampleTypeSpecificationByIDOptions`	Optional filter object to control what related data is included (e.g., expand options for nested data).

Returns

Promise<any>

A Promise that resolves to an object containing all data for the specified metadata field, including its type, validation rules, and display settings.

Example

// Fetch a specific metadata field specification
const spec = await eLabSDK2.Inventory.Sample.getSampleTypeSpecificationByID(5, 123);
console.log(`Field name: ${spec.name}`);
console.log(`Field type: ${spec.fieldType}`);
console.log(`Required: ${spec.isRequired}`);

Example

// Fetch specification with expanded data
const spec = await eLabSDK2.Inventory.Sample.getSampleTypeSpecificationByID(
  5,
  123,
  { expand: ['options', 'validationRules'] }
);
if (spec.options) {
  console.log('Available options:', spec.options);
}

getSamplesByID

Static getSamplesByID(sampleIDs, filter?): Promise<Sample[]>

Fetch multiple samples by their sample IDs in a single request.

This retrieves information for multiple samples at once, which is more efficient
than making individual requests for each sample. Use this when you need to fetch
data for multiple samples (e.g., displaying a list of selected samples, batch operations).

Parameters

Name	Type	Description
`sampleIDs`	`number`[]	Array of sample IDs to fetch.
`filter?`	`Object`	Optional filter object to control what data is included. Use the expand property to include related data.

Returns

Promise<Sample[]>

A Promise that resolves to an array of Sample objects.

Example

// Fetch multiple samples by ID
const sampleIds = [12345, 12346, 12347];
const samples = await eLabSDK2.Inventory.Sample.getSamplesByID(sampleIds);
samples.forEach(sample => {
  console.log(`${sample.name}: ${sample.barcode}`);
});

Example

// Fetch samples with quantity information
const samples = await eLabSDK2.Inventory.Sample.getSamplesByID(
  [100, 101, 102],
  { expand: ['quantity', 'meta'] }
);
console.log(`Total samples fetched: ${samples.length}`);

setSampleParent

Static setSampleParent(sampleIDs, parentID): Promise<AxiosResponse<any, any, {}>>

Set a single parent sample for multiple samples.

This establishes a parent-child relationship between samples, useful for tracking
sample lineage and derivation. Multiple child samples can be assigned to the same
parent sample in a single operation. This is the legacy method for single-parent
relationships; for multiple parents, use setSampleParents() instead.

Parameters

Name	Type	Description
`sampleIDs`	`number`[]	Array of sample IDs that will become child samples.
`parentID`	`number`	The ID of the sample that will become the parent of all specified samples.

Returns

Promise<AxiosResponse<any, any, {}>>

A Promise that resolves to the server response indicating success or failure of the operation.

Example

// Set a parent for multiple samples
const childSampleIds = [101, 102, 103];
const parentSampleId = 100;
const response = await eLabSDK2.Inventory.Sample.setSampleParent(
  childSampleIds,
  parentSampleId
);
console.log('Parent set successfully');

Example

// Link aliquots to their source sample
const aliquotIds = [501, 502, 503];
const sourceSampleId = 500;
await eLabSDK2.Inventory.Sample.setSampleParent(aliquotIds, sourceSampleId);
console.log('All aliquots now linked to source sample');

setSampleParents

Static setSampleParents(payload): Promise<SetSampleParentsResponse>

Set multiple parent samples for multiple samples (up to 5 parents per sample).

This establishes multiple parent-child relationships for samples, allowing complex
sample lineage tracking. This is useful for samples derived from multiple sources,
such as mixed compounds or pooled samples. The feature must be enabled via the
'MultipleParentSamplesPhase2' feature toggle.

Important: This method is limited to a maximum of 5 parent samples per sample.

Parameters

Name	Type	Description
`payload`	`Object`	{ sampleIds: number[], parentIds: number[] }
`payload.parentIds`	`NoMoreThan`<`5`, `number`>	Array of up to 5 parent sample IDs. All specified samples will be assigned these parents.
`payload.sampleIds`	`number`[]	Array of sample IDs that will become child samples.

Returns

Promise<SetSampleParentsResponse>

A Promise that resolves to SetSampleParentsResponse containing either success status or error details.

Example

// Set multiple parents for samples (e.g., pooled sample from two sources)
const result = await eLabSDK2.Inventory.Sample.setSampleParents({
  sampleIds: [1001],
  parentIds: [100, 101]
});
if (result.success) {
  console.log('Parents set successfully');
} else {
  console.error(`Error: ${result.error}`);
}

Example

// Link multiple derived samples to their sources
const result = await eLabSDK2.Inventory.Sample.setSampleParents({
  sampleIds: [201, 202, 203],
  parentIds: [100, 101, 102]
});
console.log(result.success ? 'Success' : result.error);

Example

// Handle errors when setting parents
try {
  const result = await eLabSDK2.Inventory.Sample.setSampleParents({
    sampleIds: [1, 2, 3],
    parentIds: [10, 11]
  });
  if (!result.success) {
    if (result.error === 'Maximum number of parents exceeded') {
      console.error('Too many parent samples specified (max 5)');
    } else if (result.error === 'Sample cannot reference itself as parent') {
      console.error('A sample cannot be its own parent');
    }
  }
} catch (error) {
  console.error('Failed to set parents:', error);
}