Class Story

Base class for all Shortcut resources. Provides methods for creating, updating, and deleting resources.

Remarks

Related: StoriesService for the service managing stories.

Story

Hierarchy (view full)

Implements

Constructors

constructor

Properties

_labels appUrl archived availableOperations blocked blocker branches changedFields comments commits completed completedAt completedAtOverride createFields createdAt customFields deadline description entityType epicId estimate externalId externalLinks files followerIds groupId groupMentionIds id iterationId labelIds leadTime linkedFiles memberMentionIds mentionIds movedAt name ownerIds position previousIterationIds projectId pullRequests requestedById service started startedAt startedAtOverride stats storyLinks storyTemplateId storyType syncedItem tasks unresolvedBlockerComments updatedAt workflowId workflowStateId baseUrl

Accessors

epic iteration labels owners team workflow

Methods

_preSave addFile addTask blocks comment create cycleTime delete duplicates history instantiateComments instantiateCustomFields instantiateLabels instantiateLinks instantiateTasks relatesTo save state timeInDevelopment update workflowHistory

Constructors

constructor

Properties

Private _labels

_labels: Label[] = []

appUrl

appUrl: string

archived

archived: boolean

availableOperations

availableOperations: ResourceOperation[] = ...

The available operations for the resource, any not in this list will raise an error when called

blocked

blocked: boolean

blocker

blocker: boolean

branches

branches: object[]

Internal changedFields

changedFields: string[] = []

Fields that have been changed, used to determine what to update. It is not recommended to access this property directly.

comments

comments: default[]

commits

commits: object[]

completed

completed: boolean

completedAt

completedAt: null | Date

completedAtOverride

completedAtOverride: null | Date

createFields

createFields: string[] = []

Fields that are used when creating a new resource

createdAt

createdAt: Date

customFields

customFields: default[]

deadline

deadline: null | Date

description

description: string

entityType

entityType: string

epicId

epicId: null | number

estimate

estimate: null | number

externalId

externalId: null | string

externalLinks

externalLinks: string[]

files

files: object[]

followerIds

followerIds: string[]

groupId

groupId: null | string

groupMentionIds

groupMentionIds: string[]

id

id: number

iterationId

iterationId: null | number

labelIds

labelIds: number[]

leadTime

leadTime: number

linkedFiles

linkedFiles: object[]

memberMentionIds

memberMentionIds: string[]

mentionIds

mentionIds: string[]

movedAt

movedAt: null | Date

name

name: string

ownerIds

ownerIds: string[]

position

position: number

previousIterationIds

previousIterationIds: number[]

projectId

projectId: null | number

pullRequests

pullRequests: PullRequestInterface[]

requestedById

requestedById: string

service

service: BaseService<BaseResource<default>, default> | BaseSearchableService<BaseResource<default>, default>

started

started: boolean

startedAt

startedAt: null | Date

startedAtOverride

startedAtOverride: null | Date

stats

stats: object

storyLinks

storyLinks: default[]

storyTemplateId

storyTemplateId: null | string

storyType

storyType: string

syncedItem

syncedItem: object

tasks

tasks: default[]

unresolvedBlockerComments

unresolvedBlockerComments: number[]

updatedAt

updatedAt: null | Date

workflowId

workflowId: number

workflowStateId

workflowStateId: number

Static baseUrl

baseUrl: string = 'https://api.app.shortcut.com/api/v3/stories'

Accessors

epic

iteration

labels

  • get labels(): Label[]

  • Returns Label[]

  • set labels(labels): void

  • Set the labels associated with the story. In order for creating/updating of stories to work properly with labels, you must set the labels to a new array of labels, rather than modifying the existing array. This allows the Story class to track changes to the labels.

    Parameters

    Returns void

owners

team

  • get team(): null | Promise<Team>

  • Get the team assigned to the story, labelled as "Group" in the Shortcut API

    Returns null | Promise<Team>

workflow

  • get workflow(): Promise<WorkflowStateInterface>

  • Returns Promise<WorkflowStateInterface>

Methods

Protected _preSave

  • _preSave(): Promise<void>

  • This method can be overridden by derived classes to perform any necessary operations before saving the resource

    Returns Promise<void>

addFile

addTask

  • addTask(task): Promise<void>

  • Adds a subtask to the story, these are visible in Shortcut as a to-do list of items that need to be completed.

    Parameters

    • task: string

    Returns Promise<void>

blocks

  • blocks(story): Promise<void>

  • Provide a story or story ID to indicate that this work blocks another story from being ready to start.

    Parameters

    Returns Promise<void>

comment

  • comment(comment): Promise<default>

  • Parameters

    • comment: string

    Returns Promise<default>

create

  • create(): Promise<Story>

  • Create a new instance of the resource, using the current object's properties. Use the xCreateData interface to determine which fields are available for creation.

    Returns Promise<Story>

    • A Promise that resolves with the newly created instance.

    Throws

    • Throws an error if the HTTP request fails.

cycleTime

  • cycleTime(): number

  • Calculates the cycle time of a story in hours.

    Returns number

    • The cycle time in hours.

    Throws

    • If the story is not completed or has not been started.

delete

  • delete(): Promise<void>

  • Delete the current instance of the resource.

    Returns Promise<void>

    • A Promise that resolves when the resource has been deleted.

    Throws

    • Throws an error if the HTTP request fails.

duplicates

  • duplicates(story): Promise<void>

  • Provide a story or story ID to indicate that this story is duplicative of another story.

    Parameters

    Returns Promise<void>

history

Private instantiateComments

Private instantiateCustomFields

Private instantiateLabels

Private instantiateLinks

Private instantiateTasks

relatesTo

  • relatesTo(story): Promise<void>

  • Provide a story or story ID to indicate that this story is related to another story.

    Parameters

    Returns Promise<void>

save

  • save(): Promise<void>

  • Save the current instance of the resource. If the resource already exists (has an ID), it will be updated. Otherwise, it will be created using the fields createFields.

    Returns Promise<void>

state

  • state(): Promise<WorkflowStateType>

  • Get the state of the story, i.e. Finished, Started, Unstarted

    Returns Promise<WorkflowStateType>

timeInDevelopment

  • timeInDevelopment(): Promise<number>

  • Calculates the time a story has been in development in hours.

    Returns Promise<number>

    • The time in development in hours.

    Throws

    • If the story is already finished or not started.

update

  • update(): Promise<void>

  • Update the current instance of the resource with the changed fields.

    Returns Promise<void>

    • A Promise that resolves when the resource has been updated.

    Throws

    • Throws an error if the HTTP request fails.

workflowHistory

  • workflowHistory(): Promise<FlatHistory[]>

  • Get the history of workflow changes for the story as a flat array. See FlatHistory for the structure of the flat history. This is useful for making calculations or determining when specific events occurred as it reduces the complexity of the history data. Note however that there is additional network overhead in fetching the history data. There is an initial request to fetch all workflow history, and each subsequent Member is fetched individually.

    Returns Promise<FlatHistory[]>

Settings

Member Visibility

Theme

On This Page

constructor_labelsappUrlarchivedavailableOperationsblockedblockerbrancheschangedFieldscommentscommitscompletedcompletedAtcompletedAtOverridecreateFieldscreatedAtcustomFieldsdeadlinedescriptionentityTypeepicIdestimateexternalIdexternalLinksfilesfollowerIdsgroupIdgroupMentionIdsiditerationIdlabelIdsleadTimelinkedFilesmemberMentionIdsmentionIdsmovedAtnameownerIdspositionpreviousIterationIdsprojectIdpullRequestsrequestedByIdservicestartedstartedAtstartedAtOverridestatsstoryLinksstoryTemplateIdstoryTypesyncedItemtasksunresolvedBlockerCommentsupdatedAtworkflowIdworkflowStateIdbaseUrlepiciterationlabelsownersteamworkflow_preSaveaddFileaddTaskblockscommentcreatecycleTimedeleteduplicateshistoryinstantiateCommentsinstantiateCustomFieldsinstantiateLabelsinstantiateLinksinstantiateTasksrelatesTosavestatetimeInDevelopmentupdateworkflowHistory