All docs This doc
Skip to end of metadata
Go to start of metadata


Overview

The following operations allow you to work with stories. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with stories, see Sample configuration

OperationDescription

createStory

Creates a story in the specified project.

getStoryRetrieves a single story from the specified project.
listStoriesRetrieves the list of stories from the specified project..
updateStoryModifies a single story in the specified project.

Operation details

This section provides further details on the operations related to stories.

Creating a story in the specified project

The createStory operation creates a story in the specified project.

createStory
<agilezen.createStory>
    <details>{$ctx:details}</details>
    <size>{$ctx:size}</size>
    <priority>{$ctx:priority}</priority>
    <color>{$ctx:color}</color>
    <phaseId>{$ctx:phaseId}</phaseId>
    <ownerId>{$ctx:ownerId}</ownerId>
    <ownerUserName>{$ctx:ownerUserName}</ownerUserName>
    <text>{$ctx:text}</text>
    <tags>{$ctx:tags}</tags>
    <tasks>{$ctx:tasks}</tasks>
	<projectId>{$ctx:projectId}</projectId>
</agilezen.createStory>
Properties
  • details: The details of the story in markdown format.
  • size: The story's size.
  • priority: The story's priority.
  • color: Potential colors: grey, blue, red, green, orange, yellow, purple, and teal.
  • phaseId: The ID or object representing the phase in which to create the story.
  • ownerId: The ID of the user who will be assigned the story.
  • ownerUserName: The username of the user who will be assigned the story.
  • text: The text of the story, displayed on the card.
  • tags: An array of tag IDs or names to apply to the story.
  • tasks: An array of task objects to add to the story.
  • projectId: The ID of the project to which the story belongs.
   Sample request

Following is a sample REST/JSON request that can be handled by the createStory operation.

Sample Request for createStory
{
   
    "apiUrl": "https://agilezen.com",
    "apiKey": "7fb8d03c21d748e09fb31b62b1ba7d13",
    "format": "json",
    "enrichments": "comments,details,metrics,milestones,steps,tags,tasks",
    "details": "This stroy is about the 1st case of the 1st scenario of SupportBee Business Scenarios.",
    "size": 6,
    "priority": 5,
    "color": "red",
    "phaseId": "93581",
    "ownerId": "93581",
    "ownerUserName": "Palamayuran",
    "text": "SupportBee Scenarios - S01C01",
    "tags": ["SupportBee", "Formstack"],
    "tasks": [{
	   "id": 2291380,
	   "text": "Description for Task 0005",
	   "createTime": "2015-05-14T07:28:36.286528Z",
	   "status": "incomplete"
	}],
    "projectId": 70025
}
Related AgileZen documentation

http://dev.agilezen.com/resources/stories.html#create_a_new_story

Retrieving a single story from the specified project

The getStory operation retrieves a single comment from the specified story.

getStory
<agilezen.getStory>
    <storyId>{$ctx:storyId}</storyId>
	<projectId>{$ctx:projectId}</projectId>
</agilezen.getStory>
Properties
  • storyId: The ID of the story whose details would be retrieved.
  • projectId: The ID of the project to which the story belongs.
   Sample request

Following is a sample REST/JSON request that can be handled by the getStory operation.

Sample Request for getStory
{
    "apiUrl": "https://agilezen.com",
    "apiKey": "7fb8d03c21d748e09fb31b62b1ba7d13",
    "format": "json",
    "enrichments": "comments,details,metrics,milestones,steps,tags,tasks",
    "storyId": 1,
    "projectId": 70025
}
Related AgileZen documentation

http://dev.agilezen.com/resources/stories.html#get_a_story

Retrieving the list of stories from the specified project

The listStories operation retrieves the list of stories from the specified project.

listStories
<agilezen.listStories>
    <projectId>{$ctx:projectId}</projectId>
    <filters>{$ctx:filters}</filters>
   	<page>{$ctx:page}</page>
	<pageSize>{$ctx:pageSize}</pageSize>
</agilezen.listStories>
Properties
  • projectId: The ID of the project to which the story belongs.
  • filters: Filter queries which the user can use to filter the returned data.
  • page: The number of the page to be returned when response is paginated.
  • pageSize: The number of responses to be returned in a call when response is paginated.
   Sample request

Following is a sample REST/JSON request that can be handled by the listStories operation.

Sample Request for listStories
{
    "apiUrl": "https://agilezen.com",
    "apiKey": "7fb8d03c21d748e09fb31b62b1ba7d13",
    "format": "json",
    "enrichments": "comments,details,metrics,milestones,steps,tags,tasks",
    "projectId": 70025,
    "filters": "status:blocked",
    "page": 2,
    "pageSize": 1
}
Related AgileZen documentation

http://dev.agilezen.com/resources/stories.html#list_stories_within_a_project

Modifying a single story in the specified project

The updateStory operation modifies a single story in the specified project.

updateStory
<agilezen.updateStory>
     <details>{$ctx:details}</details>
     <size>{$ctx:size}</size>
     <priority>{$ctx:priority}</priority>
     <color>{$ctx:color}</color>
     <phaseId>{$ctx:phaseId}</phaseId>
     <ownerId>{$ctx:ownerId}</ownerId>
     <ownerUserName>{$ctx:ownerUserName}</ownerUserName>
     <text>{$ctx:text}</text>
     <projectId>{$ctx:projectId}</projectId>
     <status>{$ctx:status}</status>
     <blockedReason>{$ctx:blockedReason}</blockedReason>
	<storyId>{$ctx:storyId}</storyId>
</agilezen.updateStory>
Properties
  • details: The details of the story in markdown format.
  • size: The story's size.
  • priority: The story's priority.
  • color: Potential colors: grey, blue, red, green, orange, yellow, purple, and teal.
  • phaseId: The ID or object representing the phase in which to create the story.
  • ownerId: The ID of the user who will be assigned the story.
  • ownerUserName: The username of the user who will be assigned the story.
  • text: The text of the story, displayed on the card.
  • projectId: The ID of the project to which the story belongs.
  • status: The story's status. Valid values for stories on board: started, ready, blocked.
  • blockedReason: The reason the story is blocked, if its status is set to 'blocked'.
  • storyId: The ID of the story to update.
   Sample request

Following is a sample REST/JSON request that can be handled by the updateStory operation.

Sample Request for updateStory
{
    "apiUrl": "https://agilezen.com",
    "apiKey": "7fb8d03c21d748e09fb31b62b1ba7d13",
    "format": "json",
    "enrichments": "comments,details,metrics,milestones,steps,tags,tasks",
    "details": "Updated - This stroy is about the 1st case of the 1st scenario of SupportBee Business Scenarios.",
    "size": 3,
    "priority": 4,
    "color": "yellow",
    "phaseId": "93581",
    "ownerId": "93581",
    "ownerUserName": "Palamayuran",
    "text": "Updated - SupportBee Scenarios - S01C01",
    "projectId": 70025,
    "status": "blocked",
    "blockedReason": "Blocked due to the delay in estimate acceptance by the client.",
    "storyId": 1
}
Related AgileZen documentation

http://dev.agilezen.com/resources/stories.html#update_a_story

Sample configuration

Following is a sample proxy service that illustrates how to connect to AgileZen with the init operation and use the createStory operation. The sample request for this proxy can be found in the createStory sample request.

Sample Proxy
<?xml version="1.0" encoding="UTF-8"?>
<proxy name="agilezen_createStory" startOnLoad="true" statistics="disable" trace="disable" transports="https,http" xmlns="http://ws.apache.org/ns/synapse">
   <target>
      <inSequence onError="faultHandlerSeq">
         <property name="apiUrl" expression="json-eval($.apiUrl)"/>
         <property name="apiKey" expression="json-eval($.apiKey)"/>
         <property name="format" expression="json-eval($.format)"/>
         <property name="details" expression="json-eval($.details)"/>
         <property name="size" expression="json-eval($.size)"/>
         <property name="priority" expression="json-eval($.priority)"/>
         <property name="color" expression="json-eval($.color)"/>
         <property name="phaseId" expression="json-eval($.phaseId)"/>
         <property name="ownerId" expression="json-eval($.ownerId)"/>
         <property name="ownerUserName" expression="json-eval($.ownerUserName)"/>
         <property name="text" expression="json-eval($.text)"/>
         <property name="tags" expression="json-eval($.tags)"/>
         <property name="tasks" expression="json-eval($.tasks)"/>
         <property name="enrichments" expression="json-eval($.enrichments)"/>
         <property name="projectId" expression="json-eval($.projectId)"/>
         <agilezen.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <apiKey>{$ctx:apiKey}</apiKey>
            <format>{$ctx:format}</format>
            <enrichments>{$ctx:enrichments}</enrichments>
         </agilezen.init>
         <agilezen.createStory>
            <details>{$ctx:details}</details>
            <size>{$ctx:size}</size>
            <priority>{$ctx:priority}</priority>
            <color>{$ctx:color}</color>
            <phaseId>{$ctx:phaseId}</phaseId>
            <ownerId>{$ctx:ownerId}</ownerId>
            <ownerUserName>{$ctx:ownerUserName}</ownerUserName>
            <text>{$ctx:text}</text>
            <tags>{$ctx:tags}</tags>
            <tasks>{$ctx:tasks}</tasks>
            <projectId>{$ctx:projectId}</projectId>
         </agilezen.createStory>
         <respond/>
      </inSequence>
      <outSequence>
         <send/>
      </outSequence>
   </target>
   <description/>
</proxy>
  • No labels