[IN:13034]` by miss525 · Pull Request #72 · Inflectra/spira-documentation

miss525 · 2026-07-03T12:41:09Z

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

simonhbor

Some formatting changes to use admonitions without emojis or quotes. And if possible can we make the sync direction tables more consistent? Many seem a little different than what we have for Jira

simonhbor · 2026-07-06T12:30:16Z

+| :--- | :--- | :--- | :--- |
+| **bidirectional** (Default) | **New & Updates:** <br>monday.com <-> Spira | **New & Updates:** <br>monday.com <-> Spira | **New & Updates:** <br>monday.com -> Spira <br>*(Creates Spira Tasks)* |
+| **monday_to_spira** | **New & Updates:** <br>monday.com -> Spira | **New & Updates:** <br>monday.com -> Spira | **New & Updates:** <br>monday.com -> Spira <br>*(Creates Spira Tasks)* |
+| **spira_to_monday** | **New & Updates:** <br>Spira -> monday.com | **New & Updates:** <br>Spira -> monday.com | *(Ignored / Not Synced)* |


Given everything is new and updates apart from the final ignored row can you please simplify the table by adding something above it that everything apples for new and updates (and describe what that means)

I updated the Monday.com sync table and added description. Please let me know if I can keep doing the same and if its ok now.

simonhbor · 2026-07-06T12:31:02Z

+| **monday_to_spira** | **New & Updates:** <br>monday.com -> Spira | **New & Updates:** <br>monday.com -> Spira | **New & Updates:** <br>monday.com -> Spira <br>*(Creates Spira Tasks)* |
+| **spira_to_monday** | **New & Updates:** <br>Spira -> monday.com | **New & Updates:** <br>Spira -> monday.com | *(Ignored / Not Synced)* |
+
+>⚠️ **Note on Descriptions:** Due to the nature of text fields in monday.com (which only support plain text), descriptions will only be synced from monday.com to Spira **on creation**, but will sync from Spira to monday.com **all the time** (continuous update).


Why is this in a quote section? That is not a standard pattern in our docs. I suggest removing the quotes and emoji and making this an info admonintion

simonhbor · 2026-07-06T12:31:17Z

+| **clickup_to_spira** | ClickUp -> Spira <br>*(New Only)* | ClickUp -> Spira | ClickUp -> Spira | ClickUp -> Spira |
+| **spira_to_clickup** | *(Not Synced)* | *(Not Synced)* | Spira -> ClickUp <br>*(New Only)* | Spira -> ClickUp <br>*(New Only)* |
+
+> ⚠️ **Note:** ClickUp integration only supports creating *new* items when flowing from Spira to ClickUp. Subsequent updates made to an item inside Spira will not sync back to ClickUp.


Why is this in a quote section? That is not a standard pattern in our docs. I suggest removing the quotes and emoji and making this an info admonintion

simonhbor · 2026-07-06T12:31:34Z

+| **Attachments** | **New, Updates, & Deletes** | **New & Updates** | Updates match as new document versions. Deleting in Salesforce removes it from Spira. |
+| **Comments** | **New Posts & Comments** | **New Posts & Comments** | Requires Salesforce 'Feed Post and Comments' component. |
+
+> ⚠️ **Technical Constraint Rules:** > 1. Custom fields/objects automatically get appended with `__c` by Salesforce. **Do not** manually add the `__c` prefix/suffix inside your Spira Data Mapping configuration screens.


See previous comments about quote sections

simonhbor · 2026-07-06T12:32:16Z

+| **Incidents** | **New & Updates** | **New & Updates** | Full two-way field synchronization supported. |
+| **Requirements** | **New & Updates** | *(Not Synced)* | Strict one-way synchronization to Spira only. |
+| **Attachments** | **New, Updates, & Deletes** | **New & Updates** | Updates match as new document versions. Deleting in Salesforce removes it from Spira. |
+| **Comments** | **New Posts & Comments** | **New Posts & Comments** | Requires Salesforce 'Feed Post and Comments' component. |


there are no sync areas here so this looks different to the others - is there a reason for that?

The reason was that there are no sync modes variaty as for Jira.
However, it is now follow the same pattern

simonhbor · 2026-07-06T12:32:29Z

+| **Requirements** | Bidirectional (ServiceNow <-> Spira) | One-Way (ServiceNow -> Spira Only) |
+| **Attachments** | Bidirectional (Synced on Creation Only) | *(Not Synced on Updates)* |
+
+> ⚠️ **Note on Field Updates:** While new records can originate from either platform, the integration service tracks on-going field changes exclusively from **ServiceNow into Spira**. Modifications made to an item inside Spira after its initial creation will not sync back to ServiceNow.


see previous comments about quotes

simonhbor · 2026-07-06T12:33:15Z

+
+| Artifact / Entity | Sync Direction: New Item Creation | Sync Direction: Subsequent Updates |
+| :--- | :--- | :--- |
+| **Incidents** | Bidirectional (ServiceNow <-> Spira) | One-Way (ServiceNow -> Spira Only) |


Not sure the words Bidirectional or one-way add anything here - we skip that entirely for Jira so suggest doing the same here and keep it simpler

simonhbor · 2026-07-06T12:33:29Z

+| **User Stories / Requirements** | **New & Updates** | *(Not Synced)* | User stories automatically sync one-way from VersionOne into Spira as Requirements. |
+| **Sprints / Releases** | **New Only** | *(Not Synced)* | Sprints/Timeboxes created in VersionOne automatically populate as Releases in Spira. |
+
+> ⚠️ **Technical Constraint Rules:**


see previous comments on quotes

simonhbor · 2026-07-06T12:33:50Z

+
+| Artifact / Entity | VersionOne to Spira Flow | Spira to VersionOne Flow | Notes / Constraints |
+| :--- | :--- | :--- | :--- |
+| **Defects / Incidents** | **New & Updates** | **New Only** | Spira acts as a read-only viewer for updates once a defect is replicated to VersionOne. |


Can we make this be more like Jira?

simonhbor · 2026-07-06T12:34:03Z

+| :--- | :--- | :--- | :--- | :--- |
+| **Bidirectional** (Default) | (not synced) | (not synced) | YouTrack <-> Spira | YouTrack <-> Spira <br>*(For types specified in Custom 02)* |
+
+> ⚙️ **Task vs. Incident Differentiation (`Custom 02`):** By default, all YouTrack issues map directly to Spira Incidents. To separate specific issue types out as Spira Tasks, populate the **Custom 02** field at the system level with a comma-separated list of the exact YouTrack issue type names (e.g., `Task,Epic`).


see previous comments on quotes

I updated the Monday.com sync table and added description. Please let me know if I can keep doing the same and if its ok now.

I updated the YouTrack sync table and added description. Please let me know if I can keep doing the same and if its ok now.

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

brgruber92

This is a great work! I added a few comments for some places that need correction, but in general, our docs will look great!

brgruber92 · 2026-07-08T21:00:09Z

The table has a few inconsistencies. I think this is how it actually work:

I asked Kiro to update the table code, so feel free to replace it:
The table below shows a summary of how data is synced from/to Spira and Azure DevOps (TFS) based on the configured Sync Direction:

Sync Mode Releases Requirements Incidents Tasks

Bidirectional (Default) ADO <-> Spira ADO -> Spira ADO <-> Spira ADO -> Spira

UpdateSpira ADO <-> Spira ADO -> Spira ADO -> Spira ADO -> Spira

UpdateADO ADO <-> Spira ADO -> Spira Spira -> ADO ADO -> Spira

Notes:

Incidents are the only artifact type affected by the Sync Direction setting. In bidirectional mode, whichever side was updated most recently wins. In UpdateSpira or UpdateADO mode, updates are forced in one direction. However, creation of new incidents always flows both ways regardless of the setting — the direction only controls how updates to existing mapped incidents are handled.

Releases are synced bidirectionally but only for creation: when a Spira incident references a release not yet mapped in ADO, a new TFS iteration is created; conversely, when a TFS work item references an iteration not yet mapped in Spira, a new Spira release is created. Releases are never updated in either direction — they are only created on-demand as part of artifact sync. This behavior is not affected by the Sync Direction setting.

please find a formatted raw text of my suggestion below here: https://drive.google.com/drive/folders/16t_THjXaVM2k3Dyh_7mwUFAdnwC7oPXK?usp=sharing

brgruber92 · 2026-07-08T21:06:19Z


 Similarly, as the requirements are decomposed into discrete project tasks in Spira, the integration service will automatically load these new tasks into TFS as task work items where the development team can manage their lifecycle, with schedule and progress changes in TFS being reflected back in Spira.

-!!! danger "Set up data synchronization"     


I think we should keep this warning for all the plugins, shouldn't we?

brgruber92 · 2026-07-08T21:11:25Z

+
+!!! info "Synchronization Notes"
+
+    **Attachment Synchronization**


The table is correct. Th only inconsistency is that the attachment flow is actually bidirectional for both creation and updates, not one-way as stated.

brgruber92 · 2026-07-08T21:19:00Z

+!!! danger "Set up data synchronization"
+    **STOP! Please make sure you have first read the instructions to [set up  the data sync](Setting-up-Data-Synchronization.md) before proceeding!**
+
+This data sync plugin can sync the following information:


The table is not 100% correct, because for Releases, the direction (VersionOne → Spira) is correct, but "(New Only)" is wrong. It should say "VersionOne -> Spira" (without the "New Only" qualifier), as the code also updates existing releases/iterations

brgruber92 · 2026-07-08T21:30:07Z

+
+The table below shows a summary of how data is synced from/to Spira and Salesforce.com based on the core integration capabilities:
+
+| Sync Mode | Requirements | Incidents | Attachments | Comments |


The table is almost correct, for comments what's there is only true for incidents; for requirements, comments are SF→Spira only

brgruber92 · 2026-07-08T21:31:13Z

+| **monday_to_spira** | monday.com -> Spira | monday.com -> Spira | monday.com -> Spira |
+| **spira_to_monday** | Spira -> monday.com | Spira -> monday.com | (ignored) |
+
+#### Synchronization Notes


Can we use the pattern !!! info "Synchronization Notes" here to keep it consistent?

brgruber92 · 2026-07-08T21:40:03Z

+
+**User Synchronization**
+Tracking field ownership maps across platforms according to your choice of configuration:
+* **Auto-Map Users:** Automatically pairs users across platforms, provided their usernames are identical in both systems.


The doc's claim that auto-map works when "usernames are identical in both systems" is misleading — it actually matches the Monday display name against the Spira user mapping's external key value (which is the display name). It's not matching login usernames automatically without configuration.

Yes, Auto-Map is not really auto-map for this plugin. If it's off, no users are matched!

brgruber92 · 2026-07-08T21:42:20Z

+| Workspace / Boards | Product |
+| Users | Users |
+| Items | Incidents and Tasks |
+| Sub-items | Tasks |


Please change this to Sub-items → Incidents and Tasks (not just Tasks)

sub-items on the Task board become Tasks, sub-items on the Incident board become Incidents. They follow the same mapping as regular items.

brgruber92 · 2026-07-08T21:48:49Z

+The table below shows a summary of how data is synced from/to Spira and ClickUp based on the configured Sync Direction (**Custom 01**):
+
+| Sync Mode (`Custom 01`) | Releases | Requirements | Incidents | Tasks |
+| :--- | :--- | :--- | :--- | :--- |


For Releases: "New Only" (bidirectional & clickup_to_spira) this is wrong — the code also updates release names (just the names)

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

ninodiasamidze added 2 commits July 3, 2026 08:40

[IN:13034]`

7c062b9

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

[IN:13034]`

0fc5e80

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

miss525 assigned simonhbor and brgruber92 Jul 6, 2026

simonhbor requested changes Jul 6, 2026

View reviewed changes

simonhbor assigned miss525 and unassigned simonhbor Jul 6, 2026

ninodiasamidze added 4 commits July 6, 2026 10:10

[IN:13034]`

7a9c21b

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

[IN:13034]`

ec4ac0c

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

[IN:13034]`

2b69d63

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

[IN:13034]`

4943371

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

brgruber92 requested changes Jul 8, 2026

View reviewed changes

brgruber92 removed their assignment Jul 8, 2026

ninodiasamidze added 3 commits July 10, 2026 10:01

[IN:13034]`

a198b18

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

[IN:13034]`

549227e

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

[IN:13034]`

8839c23

Enhance the documentation for all the syncing plug ins with a diagram to show the artifact syncing directions like the Jira documentation

Sync Mode	Releases	Requirements	Incidents	Tasks
Bidirectional (Default)	ADO <-> Spira	ADO -> Spira	ADO <-> Spira	ADO -> Spira
UpdateSpira	ADO <-> Spira	ADO -> Spira	ADO -> Spira	ADO -> Spira
UpdateADO	ADO <-> Spira	ADO -> Spira	Spira -> ADO	ADO -> Spira


		Similarly, as the requirements are decomposed into discrete project tasks in Spira, the integration service will automatically load these new tasks into TFS as task work items where the development team can manage their lifecycle, with schedule and progress changes in TFS being reflected back in Spira.

		!!! danger "Set up data synchronization"


		!!! info "Synchronization Notes"

		Attachment Synchronization


		The table below shows a summary of how data is synced from/to Spira and Salesforce.com based on the core integration capabilities:

		\| Sync Mode \| Requirements \| Incidents \| Attachments \| Comments \|

Uh oh!

Conversation

miss525 commented Jul 3, 2026

Uh oh!

simonhbor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brgruber92 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants