Skip to main content

Episode Functions

To manage simulation 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 endpoint /episode/{groupName}.
  • Sends the episode name and optional parameters as the request body.
  • Returns the created episode object.
Function signature
export async function create(  
    name: string,
    groupName: string,
    optionals: {  
        draft?: boolean,
        runLimit?: number,
        category?: string,
    } & RoutingOptions = {}  
): Promise<Episode>

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 Episode 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 request URL using the provided episodeKey.
  • Executes a GET request to fetch the episode details.
  • Extracts and returns the body property of the HTTP response as an Episode object.
Function signature
export async function get(
    episodeKey: string,
    optionals: RoutingOptions = {}
): Promise<Episode>

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 Episode 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 request URL using the provided groupKey in the format:
    • /episode/in/{groupKey}
  • Executes a GET request to fetch episodes related to the specified group.
  • Extracts and returns the body property of the HTTP response as an array of Episode objects.
Function signature
export async function forGroup(
    groupKey: string,
    optionals: RoutingOptions = {}
): Promise<Episode[]>

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 Episode 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 request URL using the provided groupName and name parameters.
  • Defaults to the session's groupName if groupName is not provided.
  • Executes a GET request to retrieve the episode details.
  • Extracts and returns the body property of the HTTP response as an Episode object.
Function Signature
export async function withName(
    name: string,
    optionals: { groupName?: string } & RoutingOptions = {}
): Promise<Episode>

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 Episode 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:

  • Constructs a request URL with search parameters.
  • Uses filter, sort, first, and max options to refine the search.
  • Executes a GET request to /episode/search.
  • Extracts and returns the body property of the HTTP response as a paginated list of Episode objects.
Function signature
export async function query(
    searchOptions: GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<Page<Episode>>

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<Episode>.

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 epicenter.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 request URL using the provided episodeKey.
  • Executes a DELETE request to remove the specified episode.
  • Extracts and returns the body property of the HTTP response.
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');