/// <summary>
/// Removes a project in Pivotal (not sure this works)
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to remove</param>
/// <returns>The project that was removed</returns>
public static PivotalProject DeleteProject(PivotalUser user, PivotalProject project)
{
string url = String.Format("{0}/projects/{1}?token={2}", PivotalService.BaseUrl, project.Id.GetValueOrDefault(), user.ApiToken);
XmlDocument response = PivotalService.SubmitData(url, null, ServiceMethod.DELETE);
return(project);
}
/// <summary>
/// Removes a member from a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to remove the person from</param>
/// <param name="member">The member to remove</param>
/// <returns>The member that was removed</returns>
public static PivotalMembership RemoveMember(PivotalUser user, PivotalProject project, PivotalMembership member)
{
string url = String.Format("{0}/projects/{1}/memberships/{2}?token={3}", PivotalService.BaseUrl, project.Id.GetValueOrDefault(), member.Id.GetValueOrDefault(), user.ApiToken);
XmlDocument response = PivotalService.SubmitData(url, null, ServiceMethod.DELETE);
return(member);
}
public PivotalTrackerApi(IFormsAuthenticationService formsAuthenticationService )
{
this.formsAuthenticationService = formsAuthenticationService;
//user = new PivotalUser(Configuration.PivotalApiToken);
user = new PivotalUser(this.formsAuthenticationService.ApiToken());
}
/// <summary>
/// Gets s single story for a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <param name="storyId">The id of the story to get</param>
/// <returns>the stories for the project</returns>
public static PivotalStory FetchStory(PivotalUser user, int projectId, string storyId)
{
string url = String.Format("{0}/projects/{1}/story/{2}?token={3}", PivotalService.BaseUrl, projectId.ToString(), storyId, user.ApiToken);
XmlDocument xmlDoc = PivotalService.GetData(url);
PivotalStory story = SerializationHelper.DeserializeFromXmlDocument <PivotalStory>(xmlDoc);
return(story);
}
/// <summary>
/// Fetches current projects from Pivot for a given user
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>List of projects accessible to the user</returns>
public static IList <PivotalProject> FetchProjects(PivotalUser user)
{
string url = String.Format("{0}/projects?token={1}", PivotalService.BaseUrl, user.ApiToken);
XmlDocument xml = PivotalService.GetData(url);
PivotalProjectList projectList = SerializationHelper.DeserializeFromXmlDocument <PivotalProjectList>(xml);
return(projectList.Projects);
}
/// <summary>
/// Retrieves the user's information, including the token, from Pivotal
/// </summary>
/// <param name="login">The user's login</param>
/// <param name="password">The user's password</param>
/// <returns>A Pivotal User containing the ApiToken for the user</returns>
public static PivotalUser GetUserFromCredentials(string login, string password)
{
string url = String.Format("{0}/tokens/active", PivotalService.BaseUrlHttps);
XmlDocument xmlDoc = PivotalService.GetDataWithCredentials(url, login, password);
PivotalUser user = SerializationHelper.DeserializeFromXmlDocument <PivotalUser>(xmlDoc);
return(user);
}
/// <summary>
/// Retrieves the membership information for a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to get membership info for</param>
/// <returns>List of members in the project</returns>
public static PivotalMembershipList FetchMembers(PivotalUser user, PivotalProject project)
{
string url = String.Format("{0}/projects/{1}/memberships?token={2}", PivotalService.BaseUrl, project.Id.ToString(), user.ApiToken);
XmlDocument xml = PivotalService.GetData(url);
PivotalMembershipList memberships = SerializationHelper.DeserializeFromXmlDocument <PivotalMembershipList>(xml);
return(memberships);
}
/// <summary>
/// Updates a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from (user will be owner of the project)</param>
/// <param name="project">Project information to update</param>
/// <returns>The updated project</returns>
public static PivotalProject UpdateProject(PivotalUser user, PivotalProject project)
{
string url = String.Format("{0}/projects/{1}?token={2}", PivotalService.BaseUrl, project.Id.GetValueOrDefault(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument <PivotalProject>(project);
string projectXml = PivotalService.CleanXmlForSubmission(xml, "//project", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, projectXml, ServiceMethod.PUT);
return(SerializationHelper.DeserializeFromXmlDocument <PivotalProject>(response));
}
/// <summary>
/// Deletes a story from Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The project id</param>
/// <param name="story">The story id</param>
/// <returns>The story that was deleted</returns>
public static PivotalStory DeleteStory(PivotalUser user, string projectId, PivotalStory story)
{
string url = String.Format("{0}/projects/{1}/story/{2}?token={3}", PivotalService.BaseUrl, projectId, story.Id, user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument <PivotalStory>(story);
string storyXml = PivotalService.CleanXmlForSubmission(xml, "//story", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, storyXml, ServiceMethod.DELETE);
return(story);
}
/// <summary>
/// Adds a member to a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to get membership info for</param>
/// <param name="member">The person and role to add to the project</param>
/// <returns>The added member's identity</returns>
public static PivotalMembership AddMember(PivotalUser user, PivotalProject project, PivotalMembership member)
{
string url = String.Format("{0}/projects/{1}/memberships?token={2}", PivotalService.BaseUrl, project.Id.ToString(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument <PivotalMembership>(member);
string memberXml = PivotalService.CleanXmlForSubmission(xml, "//membership", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, memberXml, ServiceMethod.POST);
return(SerializationHelper.DeserializeFromXmlDocument <PivotalMembership>(response));
}
/// <summary>
/// Adds a note (comment) to a story
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="noteText">The text to add to the story</param>
/// <returns>The text that was added</returns>
public string AddNote(PivotalUser user, string noteText)
{
string url = String.Format("{0}/projects/{1}/stories/{2}?token={3}", PivotalService.BaseUrl, ProjectId, Id, user.ApiToken);
string storyXml = String.Format("<note><text>{0}</text></note>", WebEncoding.UrlEncode(noteText));
XmlDocument response = PivotalService.SubmitData(url, storyXml, ServiceMethod.POST);
return(noteText);
}
/// <summary>
/// Updates the story with new values
/// </summary>
/// <remarks>Uses reflection to iterate properties, so does carry some overhead in terms of performance</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>The updated story instance</returns>
public PivotalStory UpdateStory(PivotalUser user)
{
PivotalStory updatedStory = PivotalStory.UpdateStory(user, ProjectId.GetValueOrDefault().ToString(), this);
System.Reflection.PropertyInfo[] properties = this.GetType().GetProperties();
foreach (System.Reflection.PropertyInfo p in properties)
{
p.SetValue(this, p.GetValue(updatedStory, null), null);
}
return(this);
}
/// <summary>
/// Updates the task with new values
/// </summary>
/// <remarks>Uses reflection to iterate properties, so does carry some overhead in terms of performance</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="story">The story the task belongs to</param>
/// <returns>The updated task instance</returns>
public PivotalTask UpdateTask(PivotalUser user, PivotalStory story)
{
PivotalTask updatedTask = PivotalTask.UpdateTask(user, story.ProjectId.GetValueOrDefault(), story.Id.GetValueOrDefault(), this);
System.Reflection.PropertyInfo[] properties = this.GetType().GetProperties();
foreach (System.Reflection.PropertyInfo p in properties)
{
p.SetValue(this, p.GetValue(updatedTask, null), null);
}
return(this);
}
/// <summary>
/// Adds a task to the story
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The project id</param>
/// <param name="storyId">The story id</param>
/// <param name="task">The task to add</param>
/// <returns>The created task</returns>
public static PivotalTask AddTask(PivotalUser user, int projectId, int storyId, PivotalTask task)
{
string url = String.Format("{0}/projects/{1}/stories/{2}/tasks?token={3}", PivotalService.BaseUrl, projectId, storyId, user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument <PivotalTask>(task);
string taskXml = PivotalService.CleanXmlForSubmission(xml, "//story", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, taskXml, ServiceMethod.POST);
return(SerializationHelper.DeserializeFromXmlDocument <PivotalTask>(response));
}
/// <summary>
/// Fetches current releases from Pivotal and optionally reloads the cache and uses the cache
/// </summary>
/// <remarks>The cache is updated with all stories, not just releases, so this can be more intensive than intended.</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="options">Options for caching</param>
/// <returns>releases for the project</returns>
public IList <PivotalStory> FetchReleases(PivotalUser user, PivotalFetchOptions options)
{
if (options.RefreshCache)
{
_storyCache = (List <PivotalStory>)PivotalStory.FetchStories(user, Id.GetValueOrDefault());
}
if (options.UseCachedItems)
{
return(_storyCache.Where(x => x.StoryType == PivotalStoryType.release).ToList());
}
return(PivotalStory.FetchStories(user, Id.GetValueOrDefault(), PivotalFilterHelper.BuildStoryTypeFilter(PivotalStoryType.release, "")));
}
/// <summary>
/// Fetches a single project from Pivotal and optionally retrieves the stories and sets them in the Stories property
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to retrieve</param>
/// <param name="loadStories">Whether to fetch stories and save them in the Stories property</param>
/// <returns>project</returns>
public static PivotalProject FetchProject(PivotalUser user, int projectId, bool loadStories)
{
string url = String.Format("{0}/projects/{1}?token={2}", PivotalService.BaseUrl, projectId.ToString(), user.ApiToken);
XmlDocument xml = PivotalService.GetData(url);
PivotalProject project = SerializationHelper.DeserializeFromXmlDocument <PivotalProject>(xml);
if (loadStories)
{
project.LoadStories(user);
}
return(project);
}
/// <summary>
/// Fetches current stories from Pivotal and optionally reloads the cache and uses the cache
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="options">Options for caching</param>
/// <returns>stories for the project</returns>
public IList <PivotalStory> FetchStories(PivotalUser user, PivotalFetchOptions options)
{
if (options.RefreshCache)
{
_storyCache = (List <PivotalStory>)PivotalStory.FetchStories(user, Id.GetValueOrDefault());
}
if (options.UseCachedItems)
{
return(_storyCache);
}
return(PivotalStory.FetchStories(user, Id.GetValueOrDefault()));
}
/// <summary>
/// Deletes a task from a story
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The project id</param>
/// <param name="storyId">The story id</param>
/// <param name="task">The task to delete</param>
/// <returns></returns>
public static PivotalTask DeleteTask(PivotalUser user, int projectId, int storyId, PivotalTask task)
{
string url = String.Format("{0}/projects/{1}/story/{2}/task/{3}?token={4}", PivotalService.BaseUrl, projectId, storyId, task.TaskId.GetValueOrDefault().ToString(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument <PivotalTask>(task);
string taskXml = PivotalService.CleanXmlForSubmission(xml, "//task", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, taskXml, ServiceMethod.DELETE);
return(task);
}
/// <summary>
/// Gets the stories for a project using a filter to limit the data returned
/// </summary>
/// <see cref="PivotalTrackerAPI.Util.PivotalFilterHelper"/>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <param name="filter">The filter to limit the data returned</param>
/// <returns>the stories for the project</returns>
public static IList <PivotalStory> FetchStories(PivotalUser user, int projectId, string filter)
{
string url = String.Format("{0}/projects/{1}/stories?token={2}", PivotalService.BaseUrl, projectId.ToString(), user.ApiToken);
if (!string.IsNullOrEmpty(filter))
{
url += "&" + filter;
}
XmlDocument xmlDoc = PivotalService.GetData(url);
PivotalStoryList storyList = SerializationHelper.DeserializeFromXmlDocument <PivotalStoryList>(xmlDoc);
return(storyList.Stories);
}
/// <summary>
/// Retrieves tasks with an optional filter
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The project id</param>
/// <param name="storyId">The story id</param>
/// <param name="filter">Filter to pass to Pivotal</param>
/// <returns></returns>
public static IList <PivotalTask> FetchTasks(PivotalUser user, int projectId, int storyId, string filter)
{
string url = String.Format("{0}/projects/{1}/story/{2}/tasks?token={3}", PivotalService.BaseUrl, projectId, storyId, user.ApiToken);
if (!string.IsNullOrEmpty(filter))
{
url += "&" + filter;
}
XmlDocument xmlDoc = PivotalService.GetData(url);
PivotalTaskList taskList = SerializationHelper.DeserializeFromXmlDocument <PivotalTaskList>(xmlDoc);
return(taskList.Tasks);
}
public PivotalService(IMembershipService membershipService, ISessionService sessionService, ICacheProvider cacheProvider, IFormsAuthenticationService formsAuthenticationService)
{
this.membershipService = membershipService;
this.sessionService = sessionService;
this.cacheProvider = cacheProvider;
this.formsAuthenticationService = formsAuthenticationService;
var apiToken = sessionService.ApiToken();
if (String.IsNullOrEmpty(apiToken))
formsAuthenticationService.SignOut();
this.user = new PivotalUser(apiToken);
//this.projects = user.FetchProjects();
//this.projects = Projects();
}
/// <summary>
/// Gets the stories for a project using a filter to limit the data returned
/// </summary>
/// <see cref="PivotalTrackerAPI.Util.PivotalFilterHelper"/>
/// <remarks>See http://www.pivotaltracker.com/help/api?version=v3#get_iterations_with_limit_and_offset</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <param name="iterationGroup">The group of iterations to constrain the list to (use unknown or all to disregard this option)</param>
/// <param name="limit">The maximum number of iterations to return</param>
/// <param name="offset">The number of iterations to skip from the beginning of the result.</param>
/// <returns>the stories grouped by iteration for the project</returns>
public static IList <PivotalIteration> FetchIterations(PivotalUser user, int projectId, PivotalIterationGroup iterationGroup, Nullable <int> limit, Nullable <int> offset)
{
string groupSelector = "";
if (iterationGroup != PivotalIterationGroup.unknown && iterationGroup != PivotalIterationGroup.all)
{
groupSelector = "/" + iterationGroup.ToString();
}
string url = String.Format("{0}/projects/{1}/iterations{2}?token={3}", PivotalService.BaseUrl, projectId.ToString(), groupSelector, user.ApiToken);
if (limit.HasValue)
{
url += "&limit=" + limit.ToString();
}
if (offset.HasValue)
{
url += "&offset=" + offset.ToString();
}
XmlDocument xmlDoc = PivotalService.GetData(url);
PivotalIterationList iterationList = SerializationHelper.DeserializeFromXmlDocument <PivotalIterationList>(xmlDoc);
return(iterationList.Iterations);
}
/// <summary>
/// Adds a story to Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project</param>
/// <param name="story">The story to add</param>
/// <param name="saveTasks">Controls whether any tasks associated with the story should also be saved.</param>
/// <returns>The created story</returns>
public static PivotalStory AddStory(PivotalUser user, int projectId, PivotalStory story, bool saveTasks)
{
string url = String.Format("{0}/projects/{1}/stories?token={2}", PivotalService.BaseUrl, projectId.ToString(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument <PivotalStory>(story);
string storyXml = PivotalService.CleanXmlForSubmission(xml, "//story", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, storyXml, ServiceMethod.POST);
PivotalStory savedStory = SerializationHelper.DeserializeFromXmlDocument <PivotalStory>(response);
if (saveTasks)
{
foreach (PivotalTask task in story.Tasks)
{
if (task.TaskId.HasValue)
{
PivotalTask.UpdateTask(user, projectId, savedStory.Id.GetValueOrDefault(), task);
}
else
{
PivotalTask.AddTask(user, projectId, savedStory.Id.GetValueOrDefault(), task);
}
}
}
return(savedStory);
}
/// <summary>
/// Adds a member to a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to get membership info for</param>
/// <param name="member">The person and role to add to the project</param>
/// <returns>The added member's identity</returns>
public static PivotalMembership AddMember(PivotalUser user, PivotalProject project, PivotalMembership member)
{
string url = String.Format("{0}/projects/{1}/memberships?token={2}", PivotalService.BaseUrl, project.Id.ToString(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument<PivotalMembership>(member);
string memberXml = PivotalService.CleanXmlForSubmission(xml, "//membership", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, memberXml, ServiceMethod.POST);
return SerializationHelper.DeserializeFromXmlDocument<PivotalMembership>(response);
}
/// <summary>
/// Retrieves the membership information for the project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>List of members in the project</returns>
public IList<PivotalMembership> FetchMembers(PivotalUser user)
{
return FetchMembers(user, this).Memberships;
}
/// <summary>
/// Removes a project in Pivotal (not sure this works)
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to remove</param>
/// <returns>The project that was removed</returns>
public static PivotalProject DeleteProject(PivotalUser user, PivotalProject project)
{
string url = String.Format("{0}/projects/{1}?token={2}", PivotalService.BaseUrl, project.Id.GetValueOrDefault(), user.ApiToken);
XmlDocument response = PivotalService.SubmitData(url, null, ServiceMethod.DELETE);
return project;
}
/// <summary>
/// Updates a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from (user will be owner of the project)</param>
/// <returns>The updated project</returns>
public PivotalProject UpdateProject(PivotalUser user)
{
return UpdateProject(user, this);
}
/// <summary>
/// Fetches a single project from Pivotal and does not fetch the stories
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to retrieve</param>
/// <returns>project</returns>
public static PivotalProject FetchProject(PivotalUser user, int projectId)
{
return PivotalProject.FetchProject(user, projectId, false);
}
/// <summary>
/// Adds a story to Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project</param>
/// <param name="story">The story to add</param>
/// <returns>The created story</returns>
public static PivotalStory AddStory(PivotalUser user, int projectId, PivotalStory story)
{
return(AddStory(user, projectId, story, false));
}
/// <summary>
/// Updates a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from (user will be owner of the project)</param>
/// <returns>The updated project</returns>
public PivotalProject UpdateProject(PivotalUser user)
{
return(UpdateProject(user, this));
}
/// <summary>
/// Gets the stories for a project using a filter to limit the data returned
/// </summary>
/// <see cref="PivotalTrackerAPI.Util.PivotalFilterHelper"/>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <param name="filter">The filter to limit the data returned</param>
/// <returns>the stories for the project</returns>
public static IList<PivotalStory> FetchStories(PivotalUser user, int projectId, string filter)
{
string url = String.Format("{0}/projects/{1}/stories?token={2}", PivotalService.BaseUrl, projectId.ToString(), user.ApiToken);
if (!string.IsNullOrEmpty(filter))
url += "&" + filter;
XmlDocument xmlDoc = PivotalService.GetData(url);
PivotalStoryList storyList = SerializationHelper.DeserializeFromXmlDocument<PivotalStoryList>(xmlDoc);
return storyList.Stories;
}
/// <summary>
/// Gets all the stories for a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <returns>the stories for the project</returns>
public static IList<PivotalStory> FetchStories(PivotalUser user, int projectId)
{
return FetchStories(user, projectId, "");
}
/// <summary>
/// Adds a story to Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project</param>
/// <param name="story">The story to add</param>
/// <param name="saveTasks">Controls whether any tasks associated with the story should also be saved.</param>
/// <returns>The created story</returns>
public static PivotalStory AddStory(PivotalUser user, int projectId, PivotalStory story, bool saveTasks)
{
string url = String.Format("{0}/projects/{1}/stories?token={2}", PivotalService.BaseUrl, projectId.ToString(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument<PivotalStory>(story);
string storyXml = PivotalService.CleanXmlForSubmission(xml, "//story", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, storyXml, ServiceMethod.POST);
PivotalStory savedStory = SerializationHelper.DeserializeFromXmlDocument<PivotalStory>(response);
if (saveTasks)
{
foreach (PivotalTask task in story.Tasks)
{
if (task.TaskId.HasValue)
{
PivotalTask.UpdateTask(user, projectId, savedStory.Id.GetValueOrDefault(), task);
}
else
{
PivotalTask.AddTask(user, projectId, savedStory.Id.GetValueOrDefault(), task);
}
}
}
return savedStory;
}
/// <summary>
/// Updates the cache of tasks for the story and returns the list
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns></returns>
public IList <PivotalTask> LoadTasks(PivotalUser user)
{
Tasks = PivotalTask.FetchTasks(user, ProjectId.GetValueOrDefault(), Id.GetValueOrDefault(), "");
return(Tasks);
}
/// <summary>
/// Gets the stories for a project using a filter to limit the data returned
/// </summary>
/// <see cref="PivotalTrackerAPI.Util.PivotalFilterHelper"/>
/// <remarks>See http://www.pivotaltracker.com/help/api?version=v3#get_iterations_with_limit_and_offset</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <param name="iterationGroup">The group of iterations to constrain the list to (use unknown or all to disregard this option)</param>
/// <returns>the stories grouped by iteration for the project</returns>
public static IList <PivotalIteration> FetchIterations(PivotalUser user, int projectId, PivotalIterationGroup iterationGroup)
{
return(FetchIterations(user, projectId, iterationGroup, null, null));
}
/// <summary>
/// Removes a member from a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to remove the person from</param>
/// <param name="member">The member to remove</param>
/// <returns>The member that was removed</returns>
public static PivotalMembership RemoveMember(PivotalUser user, PivotalProject project, PivotalMembership member)
{
string url = String.Format("{0}/projects/{1}/memberships/{2}?token={3}", PivotalService.BaseUrl, project.Id.GetValueOrDefault(), member.Id.GetValueOrDefault(), user.ApiToken);
XmlDocument response = PivotalService.SubmitData(url, null, ServiceMethod.DELETE);
return member;
}
/// <summary>
/// Retrieves the membership information for the project and updates the property to cache the list
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>List of members in the project</returns>
public IList <PivotalMembership> LoadMembers(PivotalUser user)
{
Members = FetchMembers(user, this).Memberships;
return(Members);
}
/// <summary>
/// Gets s single story for a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <param name="storyId">The id of the story to get</param>
/// <returns>the stories for the project</returns>
public static PivotalStory FetchStory(PivotalUser user, int projectId, string storyId)
{
string url = String.Format("{0}/projects/{1}/stories/{2}?token={3}", PivotalService.BaseUrl, projectId.ToString(), storyId, user.ApiToken);
XmlDocument xmlDoc = PivotalService.GetData(url);
PivotalStory story = SerializationHelper.DeserializeFromXmlDocument<PivotalStory>(xmlDoc);
return story;
}
public static IList<PivotalNote> FetchNotes(PivotalUser user, int projectId, int storyId, string filter)
{
var url = String.Format("{0}/projects/{1}/stories/{2}/notes?token={3}", PivotalService.BaseUrl, projectId, storyId, user.ApiToken);
if (!string.IsNullOrEmpty(filter))
url += "&" + filter;
var xmlDoc = PivotalService.GetData(url);
var noteList = SerializationHelper.DeserializeFromXmlDocument<PivotalNoteList>(xmlDoc);
return noteList.Notes;
}
/// <summary>
/// Gets all the stories for a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to get stories for</param>
/// <returns>the stories for the project</returns>
public static IList <PivotalStory> FetchStories(PivotalUser user, int projectId)
{
return(FetchStories(user, projectId, ""));
}
/// <summary>
/// Fetches current projects from Pivot for a given user
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>List of projects accessible to the user</returns>
public static IList<PivotalProject> FetchProjects(PivotalUser user)
{
string url = String.Format("{0}/projects?token={1}", PivotalService.BaseUrl, user.ApiToken);
XmlDocument xml = PivotalService.GetData(url);
PivotalProjectList projectList = SerializationHelper.DeserializeFromXmlDocument<PivotalProjectList>(xml);
return projectList.Projects;
}
/// <summary>
/// Adds a note (comment) to a story
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="noteText">The text to add to the story</param>
/// <returns>The text that was added</returns>
public string AddNote(PivotalUser user, string noteText)
{
string url = String.Format("{0}/projects/{1}/stories/{2}?token={3}", PivotalService.BaseUrl, ProjectId, Id, user.ApiToken);
string storyXml = String.Format("<note><text>{0}</text></note>", WebEncoding.UrlEncode(noteText));
XmlDocument response = PivotalService.SubmitData(url, storyXml, ServiceMethod.POST);
return noteText;
}
/// <summary>
/// Fetches a single project from Pivotal and optionally retrieves the stories and sets them in the Stories property
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The id of the project to retrieve</param>
/// <param name="loadStories">Whether to fetch stories and save them in the Stories property</param>
/// <returns>project</returns>
public static PivotalProject FetchProject(PivotalUser user, int projectId, bool loadStories)
{
string url = String.Format("{0}/projects/{1}?token={2}", PivotalService.BaseUrl, projectId.ToString(), user.ApiToken);
XmlDocument xml = PivotalService.GetData(url);
PivotalProject project = SerializationHelper.DeserializeFromXmlDocument<PivotalProject>(xml);
if (loadStories)
{
project.LoadStories(user);
}
return project;
}
/// <summary>
/// Updates the cache of tasks for the story and returns the list
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns></returns>
public IList<PivotalNote> LoadNotes(PivotalUser user)
{
Notes = PivotalNote.FetchNotes(user, ProjectId.GetValueOrDefault(), Id.GetValueOrDefault(), "");
return Notes;
}
/// <summary>
/// Updates a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from (user will be owner of the project)</param>
/// <param name="project">Project information to update</param>
/// <returns>The updated project</returns>
public static PivotalProject UpdateProject(PivotalUser user, PivotalProject project)
{
string url = String.Format("{0}/projects/{1}?token={2}", PivotalService.BaseUrl, project.Id.GetValueOrDefault(), user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument<PivotalProject>(project);
string projectXml = PivotalService.CleanXmlForSubmission(xml, "//project", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, projectXml, ServiceMethod.PUT);
return SerializationHelper.DeserializeFromXmlDocument<PivotalProject>(response);
}
/// <summary>
/// Updates the cache of tasks for the story and returns the list
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns></returns>
public IList<PivotalTask> LoadTasks(PivotalUser user)
{
Tasks = PivotalTask.FetchTasks(user, ProjectId.GetValueOrDefault(), Id.GetValueOrDefault(), "");
return Tasks;
}
/// <summary>
/// Retrieves the membership information for a project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="project">The project to get membership info for</param>
/// <returns>List of members in the project</returns>
public static PivotalMembershipList FetchMembers(PivotalUser user, PivotalProject project)
{
string url = String.Format("{0}/projects/{1}/memberships?token={2}", PivotalService.BaseUrl, project.Id.ToString(), user.ApiToken);
XmlDocument xml = PivotalService.GetData(url);
PivotalMembershipList memberships = SerializationHelper.DeserializeFromXmlDocument<PivotalMembershipList>(xml);
return memberships;
}
/// <summary>
/// Updates the story with new values
/// </summary>
/// <remarks>Uses reflection to iterate properties, so does carry some overhead in terms of performance</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>The updated story instance</returns>
public PivotalStory UpdateStory(PivotalUser user)
{
PivotalStory updatedStory = PivotalStory.UpdateStory(user, ProjectId.GetValueOrDefault().ToString(), this);
System.Reflection.PropertyInfo[] properties = this.GetType().GetProperties();
foreach (System.Reflection.PropertyInfo p in properties)
{
p.SetValue(this, p.GetValue(updatedStory, null), null);
}
return this;
}
/// <summary>
/// Retrieves the membership information for the project and updates the property to cache the list
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>List of members in the project</returns>
public IList<PivotalMembership> LoadMembers(PivotalUser user)
{
Members = FetchMembers(user, this).Memberships;
return Members;
}
/// <summary>
/// Loads the stories for the project and sets them in the Stories property
/// </summary>
/// <param name="user">The account to get the ApiToken from</param>
/// <returns>List of stories</returns>
public IList<PivotalStory> LoadStories(PivotalUser user)
{
Stories = FetchStories(user);
return Stories;
}
/// <summary>
/// Removes a member from a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="member">The member to remove</param>
/// <returns>The member that was removed</returns>
public PivotalMembership RemoveMember(PivotalUser user, PivotalMembership member)
{
return RemoveMember(user, this, member);
}
/// <summary>
/// Fetches current stories from Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>stories for the project</returns>
public IList<PivotalStory> FetchStories(PivotalUser user)
{
return PivotalStory.FetchStories(user, Id.GetValueOrDefault());
}
/// <summary>
/// Removes a member from a project in Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="member">The member to remove</param>
/// <returns>The member that was removed</returns>
public PivotalMembership RemoveMember(PivotalUser user, PivotalMembership member)
{
return(RemoveMember(user, this, member));
}
/// <summary>
/// Fetches current stories from Pivotal and optionally reloads the cache and uses the cache
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="options">Options for caching</param>
/// <returns>stories for the project</returns>
public IList<PivotalStory> FetchStories(PivotalUser user, PivotalFetchOptions options)
{
if (options.RefreshCache)
_storyCache = (List<PivotalStory>)PivotalStory.FetchStories(user, Id.GetValueOrDefault());
if (options.UseCachedItems)
return _storyCache;
return PivotalStory.FetchStories(user, Id.GetValueOrDefault());
}
/// <summary>
/// Retrieves the membership information for the project
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>List of members in the project</returns>
public IList <PivotalMembership> FetchMembers(PivotalUser user)
{
return(FetchMembers(user, this).Memberships);
}
/// <summary>
/// Fetches current releases from Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <returns>releases for the project</returns>
public IList<PivotalStory> FetchReleases(PivotalUser user)
{
return PivotalStory.FetchStories(user, Id.GetValueOrDefault(), PivotalFilterHelper.BuildStoryTypeFilter(PivotalStoryType.release, ""));
}
/// <summary>
/// Deletes a task from a story without requiring a task instance
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The project id</param>
/// <param name="storyId">The story id</param>
/// <param name="taskId">The task to delete</param>
public static void DeleteTask(PivotalUser user, int projectId, int storyId, int taskId)
{
string url = String.Format("{0}/projects/{1}/story/{2}/task/{3}?token={4}", PivotalService.BaseUrl, projectId, storyId, taskId, user.ApiToken);
XmlDocument response = PivotalService.SubmitData(url, null, ServiceMethod.DELETE);
}
/// <summary>
/// Fetches current releases from Pivotal and optionally reloads the cache and uses the cache
/// </summary>
/// <remarks>The cache is updated with all stories, not just releases, so this can be more intensive than intended.</remarks>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="options">Options for caching</param>
/// <returns>releases for the project</returns>
public IList<PivotalStory> FetchReleases(PivotalUser user, PivotalFetchOptions options)
{
if (options.RefreshCache)
_storyCache = (List<PivotalStory>)PivotalStory.FetchStories(user, Id.GetValueOrDefault());
if (options.UseCachedItems)
return _storyCache.Where(x => x.StoryType == PivotalStoryType.release).ToList();
return PivotalStory.FetchStories(user, Id.GetValueOrDefault(), PivotalFilterHelper.BuildStoryTypeFilter(PivotalStoryType.release, ""));
}
/// <summary>
/// Updates a story without requiring a reference
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="projectId">The project id</param>
/// <param name="story">The story id</param>
/// <returns>The updated story instance</returns>
public static PivotalStory UpdateStory(PivotalUser user, string projectId, PivotalStory story)
{
string url = String.Format("{0}/projects/{1}/stories/{2}?token={3}", PivotalService.BaseUrl, projectId, story.Id, user.ApiToken);
XmlDocument xml = SerializationHelper.SerializeToXmlDocument<PivotalStory>(story);
string storyXml = PivotalService.CleanXmlForSubmission(xml, "//story", ExcludeNodesOnSubmit, true);
XmlDocument response = PivotalService.SubmitData(url, storyXml, ServiceMethod.PUT);
return SerializationHelper.DeserializeFromXmlDocument<PivotalStory>(response);
}
/// <summary>
/// Adds a story to Pivotal
/// </summary>
/// <param name="user">The user to get the ApiToken from</param>
/// <param name="story">The story to add</param>
/// <param name="saveTasks">Controls whether any tasks associated with the story should also be saved.</param>
/// <returns>The created story</returns>
public PivotalStory AddStory(PivotalUser user, PivotalStory story, bool saveTasks)
{
return PivotalStory.AddStory(user, this.Id.GetValueOrDefault(), story, saveTasks);
}