sitemap.xml llms.txt
Skip to main content

Episode Functions

To manage episodes within a group, use the functions exported by the Episode adapter.

Importing the adapter​

To use the functions of the Episode adapter, import it as shown:
import { episodeAdapter } from 'epicenter-libs';

The episodeAdapter namespace exports functions that make calls to the Episode API.

learn more

For descriptions of the objects used by the Episode adapter functions, read Episode Entities.

Create an episode​

To create an episode for a group, use the create() function.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The create() function:

  • Constructs a POST request to the /episode/{GROUP_NAME} endpoint.
  • Supports optional configuration such as draft mode, run limits, and categorization.
  • Returns the newly created EpisodeReadOutView object.
Function signature
export async function create(
    name: string,
    groupName: string,
    optionals: {
        draft?: boolean;
        runLimit?: number;
        category?: string;
    } & RoutingOptions = {},
): Promise<EpisodeReadOutView>

Parameters​

  • name (string): The name of the new episode. Must be unique for the group.
  • groupName (string): The name of the group where the episode is created.
  • optionals (Type: { draft?: boolean, runLimit?: number, category?: string } & RoutingOptions = {}):
    • draft (boolean): Can be used to identify episodes that are still under construction, so they are not used by the group. Default is false.
    • runLimit (number): The maximum number of runs that can be made in the scope of this episode.
    • category (string): The episode category. Optional argument to allow for establishing episode hierarchies.
    • RoutingOptions: Additional routing options. Pass network call option overrides here.
warning

The episode name cannot contain any of these characters:

`$%^*={}[]|;\"<>?\r\n

Return value​

A promise that resolves to an EpisodeReadOutView object.

Usage example​

import { episodeAdapter } from 'epicenter-libs';  

const episode = await episodeAdapter.create('myEpisode', 'myGroupName', {  
    draft: true,
    runLimit: 10
});

Retrieve episodes​

Get episode details​

To retrieve the details of an episode by episodeKey, use the get() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The get() function:

  • Constructs a GET request to the /episode/{EPISODE_KEY} endpoint.
  • Accepts optional routing overrides for network configuration.
  • Returns the corresponding EpisodeReadOutView object.
Function signature
export async function get(
    episodeKey: string,
    optionals: RoutingOptions = {},
): Promise<EpisodeReadOutView>

Parameters​

  • episodeKey (string): The unique episode key.
  • optionals (RoutingOptions): Additional routing options. Pass network call option overrides here.

Return value​

A promise that resolves to an EpisodeReadOutView object.

Usage example​

import { episodeAdapter } from 'epicenter-libs';

const episodeDetails = await episodeAdapter.get('000001796733eef0842f4d6d960997065s98');

Get episodes for a group​

To retrieve all episodes associated with a group, use the forGroup() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The forGroup() function:

  • Constructs a GET request to the /episode/in/{GROUP_KEY} endpoint.
  • Accepts optional routing overrides for network configuration.
  • Returns a list of EpisodeReadOutView objects.
Function signature
export async function forGroup(
    groupKey: string,
    optionals: RoutingOptions = {},
): Promise<EpisodeReadOutView[]>

Parameters​

  • groupKey (Type: string): The group key identifying the group.
  • optionals (Type: RoutingOptions = {}): Optional routing parameters. Pass network call option overrides here. For details, see RoutingOptions.

Return value​

A promise that resolves to an array of EpisodeReadOutView objects.

Usage example​

import { episodeAdapter } from 'epicenter-libs';

const episodes = await episodeAdapter.forGroup('0000017dd3bf540e5ada5b1e058f08a64896');

Get episode by name​

To retrieve an episode by its name and the group name, use the withName() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The withName() function:

  • Constructs a GET request to the /episode/with/{GROUP_NAME}/{EPISODE_NAME} endpoint.
  • Uses the group name provided in optionals, or defaults to the group associated with the current session.
  • Returns the matching EpisodeReadOutView object.
Function signature
export async function withName(
    name: string,
    optionals: { groupName?: string } & RoutingOptions = {},
): Promise<EpisodeReadOutView>

Parameters​

  • name (string): The name of the episode to retrieve.
  • optionals (Type: { groupName?: string } & RoutingOptions = {}): An optional object to customize the request:
    • groupName (string): The name of the group that the episode belongs to. If not provided, the function gets the groupName from session.
    • RoutingOptions: Additional routing options. Pass network call option overrides here.

Return value​

A promise that resolves to an EpisodeReadOutView object.

Usage example​

import { authAdapter, episodeAdapter } from 'epicenter-libs';

const episode = await episodeAdapter.withName('myEpisodeName');

Search for episodes​

To retrieve a filtered and paginated list of episodes, call the query() function.

learn more

For reference on search filters, read Filter and sort syntax.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The query() function:

Function signature
export async function query(
    searchOptions: GenericSearchOptions,
    optionals: RoutingOptions = {},
): Promise<Page<EpisodeReadOutView>>

Parameters​

  • searchOptions (Type: GenericSearchOptions): An object containing filter and sort parameters:
    • filter (string[]): An array of filter conditions.
    • sort (string[]): Sorting conditions.
    • first (number): The index of the page to return.
    • max (number): The maximum number of results per page.
  • optionals (Type: RoutingOptions = {}): Additional routing options. Pass network call option overrides here.

Return value​

A promise that resolves to a paginated Page<EpisodeReadOutView>.

Usage example​

import { episodeAdapter } from 'epicenter-libs';

const filter = [
     'name|=one|two',                                            // searches only for episodes named 'one' or 'two'
     'draft=false',                                              // searches only for episodes that aren't drafts
     'created>=2022-01-03T20:30:53.054Z',                        // looks for any episodes created after Jan 3rd 2022
     // 'account.shortName=acme'                                 // specifies the account, intended for admin use
     // 'project.shortName=simulations'                          // specifies the project, intended for admin use
     // 'group.name=my-group-name',                              // specifies a group name, intended for admin use
     // 'group.groupKey=0000017dd3bf540e5ada5b1e058f08k35467',   // specifies a group key, intended for admin use
];

const searchResults = await episodeAdapter.query({
     filter,
     sort: ['+episode.created'],     // sort all findings by the 'created' field (ascending)
     first: 3,                       // page should start with the 4th item found (will default to 0)
     max: 10,                        // page should only include the first 10 items
});

Delete an episode​

To delete an episode identified by episodeKey, use the remove() function.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The remove() function:

  • Constructs a DELETE request to the /episode/{EPISODE_KEY} endpoint.
  • Accepts optional routing overrides for network configuration.
  • Returns undefined when the deletion is successful.
Function signature
export async function remove(
    episodeKey: string,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters​

  • episodeKey (string): A unique episode key.
  • optionals (RoutingOptions): Additional routing options. Pass network call option overrides here.

Return value​

A promise that resolves to void when the episode is successfully deleted.

Usage example​

import { episodeAdapter } from 'epicenter-libs';

await episodeAdapter.remove('000001796733eef0842f4d6d960997861s9t');