Update

Description

Update a story. Defaults to a draft called test if change control is enabled on the story and no draft_id is provided.

Request

HTTP Method: PUT

Query Parameter Description
name Optional The story name.
description Optional A user-defined description of the story.
add_tag_names Optional An array of tag names to add to the story.
remove_tag_names Optional An array of tag names to remove from the story.
keep_events_for Optional Event retention period in seconds:
1 hour: 3600
6 hours: 21600
1 day: 86400
3 days: 259200
7 days: 604800
14 days: 1209600
30 days:2592000
60 days:5184000
90 days:7776000
180 days:15552000
365 days: 31536000
disabled Optional Boolean flag indicating whether the story is disabled from running.
locked Optional Boolean flag indicating whether the story is locked, preventing edits.
priority Optional Boolean flag indicating whether story runs with high priority.
webhook_api_enabled Optional Boolean flag indicating if webhook API is enabled. If enabling, the api_entry_action_id and api_exit_action_ids parameters must also be specified. The draft_id can also be provided if the change is being made to a non-live story.
api_entry_action_id Optional The ID of the entry action for this API enabled story (action must be of type webhook). api_exit_action_ids must also be provided and webhook_api_enabled must be set to true.
api_exit_action_ids Optional An array of IDs describing exit actions for this API enabled story (actions must be message-only mode event transformation). api_entry_action_id must also be provided and webhook_api_enabled must be set to true.
send_to_story_access_source Optional STS, STS_AND_WORKBENCH, WORKBENCH or OFF indicating if send to story is enabled and where the send to story can be used. If enabling send to story, the entry_action_id and exit_action_ids parameters must also be specified.
entry_action_id Optional The ID of the entry action for this send to story enabled story (action must be of type webhook). exit_action_ids must also be provided and send_to_story_access_source must be set to STS, STS_AND_WORKBENCH or WORKBENCH.
exit_action_ids Optional An array of IDs describing exit actions for this send to story enabled story (actions must be message-only mode event transformation). entry_action_id must also be provided and send_to_story_access_source must be set to STS, STS_AND_WORKBENCH or WORKBENCH.
send_to_story_access Optional Controls who is allowed to send to this story (TEAM, GLOBAL, SPECIFIC_TEAMS). default to TEAM. If using SPECIFIC_TEAMS must also specify list of teams' slugs in shared_team_slugs.
shared_team_slugs Optional List of teams' slugs that can send to this story. Required to set send_to_story_access to SPECIFIC_TEAMS. Defaults to [] (empty array).
send_to_story_skill_use_requires_confirmation Optional Boolean flag indicating whether workbench should ask for confirmation before running this story. Story must be enabled for workbench or send to story and workbench.
team_id Optional The ID of the team to move the story to.
folder_id Optional The ID of the folder to move the story to, or an empty value to indicate the root folder. Note that this folder must exist within the team identified by team_id, or the story's current team if team_id isn't specified.
change_control_enabled Optional Boolean flag indicating if change control is enabled.
draft_id Optional The ID of the draft to update. About drafts.
monitor_failures Optional Boolean flag indicating if monitor failures is enabled on the story.
Path Parameter Description
story_id The ID of the story.

Sample request

curl -X PUT \
  https://<<META.tenant.domain>>/api/v1/stories/<<story_id>> \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "name": "Updated Simple story",
        "description": "Updates story description"
      }'

Response

A successful request will return a JSON object describing the updated story

Field description

Parameter Description
name The story name.
user_id ID of story creator.
description A user-defined description of the story.
keep_events_for Defined event retention period in seconds.
disabled Boolean flag indicating whether story is disabled.
priority Boolean flag indicating whether story is high priority story.
send_to_story_enabled Boolean flag indicating if send to story is enabled.
send_to_story_access_source STS, STS_AND_WORKBENCH, WORKBENCH or OFF indicating where the send to story can be used.
send_to_story_access Controls who is allowed to send to this story (TEAM,GLOBAL,SPECIFIC_TEAMS).
shared_team_slugs List of teams' slugs that can send to this story when send_to_story_access is SPECIFIC_TEAMS, otherwise empty.
send_to_story_skill_use_requires_confirmation Boolean flag indicating whether workbench should ask for confirmation before running this story.
entry_agent_id The ID of the entry action for this story.
exit_agents An array of objects describing exit actions for this story.
team_id ID of team to which the story belongs.
tags An array of tags used to classify the story.
guid Unique identifier of the story.
slug An underscored representation of the story name.
created_at ISO 8601 timestamp representing date and time the story was created.
updated_at ISO 8601 timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself.
edited_at ISO 8601 timestamp representing date and time the story was last logically updated.
mode The mode of the story. LIVE or TEST
id The story ID.
folder_id ID of folder to which the story belongs.
published Boolean flag indicating whether the story is published.
change_control_enabled Boolean flag indicating if change control is enabled.
locked Boolean flag indicating whether the story is locked to changes.
owners List of user IDs that are listed as owners on the story.
draft_id ID of the updated draft.
draft_name Name of the updated draft.
monitor_failures Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled.
actions_with_monitoring List of action IDs with monitoring enabled.
recipients List of monitoring recipients for the story.

Sample response

{
  "name": "Updated Simple story",
  "user_id": 167,
  "description": "Updates story description",
  "keep_events_for": 604800,
  "disabled": false,
  "priority": false,
  "send_to_story_enabled": false,
  "send_to_story_access_source": "OFF",
  "send_to_story_access": null,
  "send_to_story_skill_use_requires_confirmation": true,
  "shared_team_slugs": [],
  "entry_agent_id": null,
  "exit_agents": [],
  "team_id": 1,
  "tags": ["Tag 1", "Tag 2"],
  "guid": "df1e838a18d20696120b41516497b017",
  "slug": "simple_story",
  "created_at": "2021-05-10T08:56:50Z",
  "updated_at": "2021-05-10T08:56:50Z",
  "edited_at": "2021-05-10T08:56:50Z",
  "mode": "LIVE",
  "id": 7981,
  "folder_id": 1,
  "published": true,
  "change_control_enabled": false,
  "locked": false,
  "owners": [1],
  "draft_id": 1234,
  "draft_name": "Updated Draft",
  "monitor_failures": false,
  "actions_with_monitoring": [],
  "recipients": [
    {
      "address": "test@example.com"
    }
  ]
}
Was this helpful?