# Where is the documentation for register projections and "\_task"?

**URL:** <https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934>\
**Category:** Get Help\
**Tags:** ansible-core\
**Created:** [June 17, 2026, 3:07pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934 "2026-06-17T15:07:06Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![briantist](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/briantist/32/130_2.png) [@briantist](https://forum.ansible.com/u/briantist)\
**Post date:** [June 17, 2026, 3:07pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/1 "2026-06-17T15:07:06Z")

</div>

I know I’ve seen documentation for this somewhere, and I just did a series of web searches with different keywords and I cannot find it anywhere.

I’m looking for how to use register projections, using `_task` in conditionals to avoid needing `register`, all of these nice features that are in core 2.21, but I can’t figure out how to find the docs anymore and I don’t remember where I saw this.

The only reference I can find now is in the [Ansible 14 porting guide](https://docs.ansible.com/projects/ansible/latest/porting_guides/porting_guide_14.html) ([the core 2.21 porting guide is just empty, even in devel](https://docs.ansible.com/projects/ansible/devel/porting_guides/porting_guide_core_2.21.html))

---

<div class="post-metadata">

**Author:** ![bvitnik](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bvitnik/32/4132_2.png) [@bvitnik](https://forum.ansible.com/u/bvitnik)\
**Post date:** [June 17, 2026, 5:19pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/2 "2026-06-17T17:19:51Z")

</div>

How about this?

> <https://github.com/ansible/ansible/pull/86241>
>
> \## SUMMARY
> 
> \### Register Projections
> 
> The functionality of the \`register\` ke…yword has been expanded to allow registration of multiple variables and inline manipulation of task output with Jinja expressions ("projections").
> 
> In addition to the existing \`register: varname\` form, the \`register\` keyword can accept a dictionary of \`varname: expression\` pairs (see examples below).
> 
> A new \`\_task\` implicit variable provides Jinja expressions access to the current task's result via its \`result\` property. Expressions under looped tasks can also now access all completed loop results and preview the final loop task result via the \`\_task.loop\_result\` property. The new \`\_task\` implicit variable is available to expressions in \`register\` and task conditionals (\`changed\_when\`, \`failed\_when\`, etc.). Registered variable values are updated and available to task conditional expressions as before, but task conditionals can now bypass \`register\` entirely by accessing \`\_task\` directly (for tasks that do not otherwise require persistence of their result).
> 
> This functionality can simplify and declutter playbooks by allowing common patterns like "Run a task, 
> register the output, pick out small parts of the output with \`set\_fact\`" to be folded directly into the task itself. Further, because the new \`register\` form is always a Jinja expression, template delimiters (\`{{ }}\`) are not required for dynamic behavior as they were with \`set\_fact\`.
> 
> Unlike \`set\_fact\`, variable registration expressions \*can\* refer to other variable expressions within the same task, and because they are evaluated lazily, can be defined in any order under \`register\` .
> 
> 
> \### Action APIs for creating dynamic hosts/groups/vars
> 
> A new \`register\_host\_variables\` public API method on \`ActionBase\` allows user action plugins to implement variable-setting functionality that was previously restricted to built-in actions or required risky use of undocumented/internal action result values.
> 
> (TBD: expand description, usage examples)
> 
> The following built-in actions have been modified to use the new API:
> \* \`set\_fact\`
> \* \`include\_vars\`
> 
> 
> \## REGISTER PROJECTION EXAMPLES
> 
> \#### Registering multiple variables from a task
> 
> \*\*Before register-projections\*\* 
> 
> \`\`\`yml
> \- shell: echo hello
> failed\_when: echo\_result.stdout is contains "goodbye"
> register: echo\_result
> 
> \- set\_fact:
> echo\_duration: "{{ echo\_result.delta }}"
> capitalized\_result: "{{ echo\_result.stdout | capitalize }}"
> \`\`\`
> 
> \*\*After register-projections\*\*
> 
> \`\`\`yml
> \- shell: echo hello
> failed\_when: \_task.result.stdout is contains "goodbye"
> register:
> echo\_result: \_task.result # The old register behavior
> echo\_duration: \_task.result.delta
> capitalized\_result: \_task.result.stdout | capitalize
> \`\`\`
> 
> \#### Advanced templating and chaining variable manipulation
> 
> \*\*Before register-projections\*\* 
> 
> \`\`\`yml
> \- shell: echo hello
> register: echo\_output
> 
> \- set\_fact:
> start\_hour: "{{ echo\_output.start | regex\_search('\\\\s(\\\\d{2}):\\\\d{2}:\\\\d{2}', '\\\\1') | first | int}}"
> 
> \- set\_fact:
> output\_message: "{{ echo\_output.stdout \* start\_hour }}"
> \`\`\`
> 
> \*\*After register-projections\*\* 
> 
> \`\`\`yml
> \- shell: echo hello
> register:
> output\_message: \_task.result.stdout \* start\_hour # Notice that start\_hour is defined below, but can still be used! The order that they're declared does not matter. 
> start\_hour: \_task.result.start | regex\_search('\\\\s(\\\\d{2}):\\\\d{2}:\\\\d{2}', '\\\\1') | first | int
> \`\`\`
> 
> \#### Using \`failed\_when\` without a register
> 
> \*\*Before register-projections\*\* 
> 
> \`\`\`yml
> \- shell: echo hello
> failed\_when: echo\_result.stdout is contains "goodbye"
> register: echo\_result
> \`\`\`
> 
> \*\*After register-projections\*\*
> 
> \`\`\`yml
> \- shell: echo hello
> failed\_when: \_task.result.stdout is contains "goodbye"
> \`\`\`
> 
> \#### Registering single loop items
> 
> \*\*Before register-projections\*\*
> 
> \`\`\`yml
> \- shell: echo {{ item }}
> loop:
> - 1
> - 2
> register: echo\_loop\_result
> 
> \- set\_fact:
> second\_echo\_stdout: "{{ echo\_loop\_result.results\[1\].stdout }}"
> \`\`\`
> 
> \*\*After register-projections\*\*
> 
> \`\`\`yml
> \- shell: echo {{ item }}
> loop:
> - 1
> - 2
> register:
> second\_echo\_stdout: \_task.loop\_results\[1\].stdout | default(0) # using default here is necessary as when the loop is on the first item, it will still try and access \`loop\_results\[1\]\` which doesn't exist yet
> \`\`\`
> 
> \##### ISSUE TYPE
> 
> \- Feature Pull Request

And some forum discussion here also:

> [@Fallible 2025.12.5 released with Register Projections and new Action API previews](https://forum.ansible.com/t/fallible-2025-12-5-released-with-register-projections-and-new-action-api-previews/44965):
>
> We’re happy to announce a new drop of the fallible experimental Ansible build, and are looking for your feedback! This one contains previews of a couple of features currently slated for release in Ansible Core 2.21: Register Projections allows the register keyword to set multiple vars using the result of arbitrary Jinja expressions. It adds a new implicit variable (\_task) for the register keyword and task conditionals (e.g., failed\_when, changed\_when, break\_when, until) to directly access the …

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [June 17, 2026, 6:37pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/3 "2026-06-17T18:37:30Z")

</div>

hey @briantist those docs are unmerged as yet. this was the initial PR to add them: [Document register projection functionality by pkingstonxyz · Pull Request #3581 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/pull/3581)

that was closed last week in favour of [Document register projections by pkingstonxyz · Pull Request #3752 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/pull/3752)

I’ve done a few reviews of the content and tried to help with some of the examples. I’m sure it’d be useful and well received to get some more feedback if you’d like to dip your toe into that PR…

you can find the PR preview build of those docs here too btw: [Ansible Core Documentation — Ansible Core Documentation](https://ansible--3752.org.readthedocs.build/projects/ansible-core/3752/)

---

<div class="post-metadata">

**Author:** ![briantist](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/briantist/32/130_2.png) [@briantist](https://forum.ansible.com/u/briantist)\
**Post date:** [June 17, 2026, 7:52pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/4 "2026-06-17T19:52:19Z")

</div>

> [@bvitnik](#):
>
> How about this?

thank you! That might be what I saw before

> [@oranod](#):
>
> those docs are unmerged as yet

Perfect thanks! Glad to see they are in progress, I’ll subscribe to that PR

---

<div class="post-metadata">

**Author:** ![pkingstonxyz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/pkingstonxyz/32/8844_2.png) [@pkingstonxyz](https://forum.ansible.com/u/pkingstonxyz)\
**Post date:** [June 18, 2026, 9:14pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/5 "2026-06-18T21:14:19Z")

</div>

Hey, I’m the author of the current docs PR. It’s been a bit slow to get reviews on that PR but it’s being worked on. Please do raise questions, concerns, comments, etc. either on the open PR [Document register projections by pkingstonxyz · Pull Request #3752 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/pull/3752) or just reply in this thread if it seems unclear/you need more examples and I’ll try and help!

---

<div class="post-metadata">

**Author:** ![briantist](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/briantist/32/130_2.png) [@briantist](https://forum.ansible.com/u/briantist)\
**Post date:** [June 18, 2026, 9:32pm UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/6 "2026-06-18T21:32:15Z")

</div>

> [@pkingstonxyz](#):
>
> if it seems unclear/you need more examples

thank you! I think I’m ok with the bits of documentation I’ve seen around so I’m not looking for any new examples or anything, this came up for me when trying to tell my coworkers about it and realizing I couldn’t find anything to link to 😅

---

<div class="post-metadata">

**Author:** ![rfc2549](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/rfc2549/32/197_2.png) [@rfc2549](https://forum.ansible.com/u/rfc2549)\
**Post date:** [June 30, 2026, 12:22am UTC](https://forum.ansible.com/t/where-is-the-documentation-for-register-projections-and-task/45934/7 "2026-06-30T00:22:03Z")

</div>

Good catch.

I happened to use the \_task variable in one of my playbooks and had to do some troubleshooting to find out what was up.