Bug 1017865

Summary:	API synchronous call report example doesn't match task group management data description
Product:	[Retired] Pulp	Reporter:	mkovacik
Component:	documentation	Assignee:	Jay Dobies <jason.dobies>
Status:	CLOSED CURRENTRELEASE	QA Contact:	pulp-qe-list
Severity:	unspecified	Docs Contact:
Priority:	medium
Version:	2.2	CC:	jason.dobies, mhrivnak, mkovacik, skarmark
Target Milestone:	---	Keywords:	Triaged
Target Release:	2.3.0
Hardware:	Unspecified
OS:	Unspecified
URL:	https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/conventions/sync-v-async.html#call-report
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2013-12-09 14:29:51 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description mkovacik 2013-10-10 16:04:07 UTC

Description of problem:
There are discrepancies in fields shown in these docs pages [1][2]:
- _href
- task_group_id

[1] https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/conventions/sync-v-async.html#call-report
[2] https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/integration/rest-api/dispatch/group.html#task-group-management


Version-Release number of selected component (if applicable):
Pulp 2.2

Actual results:
Based on listing tasks from /tasks/ path [1] seems outdated

Expected results:
[1] fixed

Additional info:
# https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/conventions/sync-v-async.html#call-report
{
 "exception": null,
 "job_id": null,
 "task_id": "0fe4fcab-a040-11e1-a71c-00508d977dff",
 "tags": [
   "pulp:repository:f16",
   "pulp:action:sync"
 ],
 "reasons": [],
 "start_time": "2012-05-17T16:48:00Z",
 "traceback": null,
 "state": "running",
 "finish_time": null,
 "schedule_id": null,
 "result": null,
 "progress": { <contents depend on the operation> },
 "response": "accepted",
 "_href": "/pulp/api/v2/tasks/0fe4fcab-a040-11e1-a71c-00508d977dff/"
}

# https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/integration/rest-api/dispatch/group.html#task-group-management

{"_href": "/pulp/api/v2/task_groups/7744e2df-39b9-46f0-bb10-feffa2f7014b/",
  "response": "running",
  "reasons": [{"resource_type": "repository", "resource_id": "test-repo", "operation": "update"}],
  "state": "running",
  "task_id": "d6b6fe8e-ff0f-40e4-bb3c-9e547f0cc4a0",
  "task_group_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b",
  "schedule_id": null,
  "progress": {},
  "result": null,
  "exception": null,
  "traceback": null,
  "start_time": "2012-05-13T23:00:02Z",
  "finish_time": null,
  "tags": ["pulp:repository:test-repo"],
}

Comment 1 Michael Hrivnak 2013-10-10 16:13:05 UTC

Can you be more explicit and descriptive about what the discrepancies are? I'm not seeing it on first look.

Comment 2 mkovacik 2013-10-11 09:25:23 UTC

fields present in [1] absent in [2]:
 - job_id

fields present in [2] absent in [1]:
- task_group_id

fields with different meaning
- _href [1] points to /pulp/api/v2/tasks/
- _href [2] points to /pulp/api/v2/task_groups/

Based on listing /pulp/api/v2/tasks/ it seems [2] is more up-to-date

Comment 3 Jay Dobies 2013-10-28 13:29:25 UTC

https://github.com/pulp/pulp/pull/682

Comment 4 Jay Dobies 2013-10-28 13:32:09 UTC

Here's what I changed:

fields present in [1] absent in [2]:
 - job_id

----- Removed this from [1], it was an old example before task groups existed.

fields present in [2] absent in [1]:
- task_group_id

----- Added this to [1] to replace job_id from above.

fields with different meaning
- _href [1] points to /pulp/api/v2/tasks/
- _href [2] points to /pulp/api/v2/task_groups/

----- I didn't touch this in this fix. The docs are correct, this is in fact what is returned. For operations that are handled in a single task, the _href refers to the task itself. For operations that *can* span multiple tasks, a list of tasks are returned and the _href for each is set to the group.

The behavior of the latter is debatable, but for the purposes of this bug, the docs are correct. If you'd like to pursue changing the values of the _hrefs, please file a new bug to start that discussion.

Comment 5 Jeff Ortel 2013-10-29 15:29:37 UTC

build: 2.3.0-0.26.beta

Comment 6 mkovacik 2013-11-04 13:13:35 UTC

Checked the job_id in latest docs[1].
With regards to 2; will file a separate bug agains the API as the _href field doesn't point to a particular task item in cases where more tasks are spawned by pulp. This breaks compatibility with case when just a single task is spawned.


[1] https://pulp-dev-guide.readthedocs.org/en/latest/conventions/sync-v-async.html#call-report

Comment 7 Preethi Thomas 2013-12-09 14:29:51 UTC

Pulp 2.3 released.