Functions for querying the BambooHR Datasets API.
Datasets are the current, non-deprecated replacement for ad-hoc custom
reporting — see BambooHR.Reports for the older, still-supported saved
Custom Reports endpoints. Datasets endpoints live under different API
version segments than the rest of this client (v1_2 for catalog/field
discovery, v2 for querying data); every function here passes the
appropriate api_version: to BambooHR.Client for you.
Summary
Functions
Queries a dataset and returns matching records.
Retrieves a paginated list of field descriptors for a dataset.
Retrieves the allowed values for one or more fields in a dataset, for use
as filter values when querying data via get_dataset_data/4.
Retrieves the catalog of datasets available for querying.
Functions
@spec get_dataset_data(BambooHR.Client.t(), String.t(), [String.t()], keyword()) :: BambooHR.Client.response()
Queries a dataset and returns matching records.
Each row in the "data" array wraps its values under a "fields"
object. Use get_dataset_fields/3 to discover available field names and
get_field_options/4 to discover valid filter values.
Parameters
client- Client configuration created withBambooHR.Client.new/1dataset_name- Machine-readable dataset identifier (seelist_datasets/1)fields- List of field names to returnopts- Optional keyword list::filter- an OData-style filter expression string (operators:eq,ne,lt,le,gt,ge,and,or,in);:order_by- comma-separated sort rules, each a field name followed byascordesc(sorted fields must also appear infields);:page- page number, defaults to 1;:page_size- records per page, defaults to 100, max 1000
Examples
iex> BambooHR.Datasets.get_dataset_data(client, "employee", ["firstName", "lastName", "status"],
...> filter: "status eq 'Active'"
...> )
{:ok, %{"data" => [%{"fields" => %{"firstName" => "Jane", "status" => "Active"}}], "meta" => %{"page" => 1}}}@spec get_dataset_fields(BambooHR.Client.t(), String.t(), map()) :: BambooHR.Client.response()
Retrieves a paginated list of field descriptors for a dataset.
Use the returned field "name" values in the fields argument to
get_field_options/4 and get_dataset_data/4.
Parameters
client- Client configuration created withBambooHR.Client.new/1dataset_name- Machine-readable dataset identifier (seelist_datasets/1)params- Optional query params:"page"(default 1) and"page_size"(default 500, max 1000)
Examples
iex> BambooHR.Datasets.get_dataset_fields(client, "employee")
{:ok, %{"name" => "employee", "fields" => [%{"name" => "status", "label" => "Status"}]}}@spec get_field_options(BambooHR.Client.t(), String.t(), [String.t()], keyword()) :: BambooHR.Client.response()
Retrieves the allowed values for one or more fields in a dataset, for use
as filter values when querying data via get_dataset_data/4.
Parameters
client- Client configuration created withBambooHR.Client.new/1dataset_name- Machine-readable dataset identifier (seelist_datasets/1)fields- List of field names to get options foropts- Optional keyword list::filters- a map narrowing which options are returned (e.g. only options that exist for active employees);:dependent_fields- a map of field name to the other fields/values its options depend on
Examples
iex> BambooHR.Datasets.get_field_options(client, "employee", ["status"])
{:ok, %{"status" => [%{"id" => "Active", "value" => "Active"}]}}@spec list_datasets(BambooHR.Client.t()) :: BambooHR.Client.response()
Retrieves the catalog of datasets available for querying.
Each entry's "name" is the machine-readable identifier used as
dataset_name in get_dataset_fields/3, get_field_options/4, and
get_dataset_data/4.
Parameters
client- Client configuration created withBambooHR.Client.new/1
Examples
iex> BambooHR.Datasets.list_datasets(client)
{:ok, %{"datasets" => [%{"name" => "employee", "label" => "Employee"}]}}