As an administrative user, I want to be able to update an existing component's description and implementation statements via the API so that I can maintain a component definition outside of GovReady-Q and automatically update component definition in GovReady-Q.
As an administrative user, I want to be able to propagate a change in a component's implementation statements to all all systems using that component, so that if I update a component definition I can have all systems consuming that component have their statements updated, too.
Update various Python and NPM libraries.
Discussion
Three changes were made to support updating components:
Added an update boolean parameter to the elements/createOSCAL API v2 endpoint to indicate an existing component should be updated;
Added an Element.synch_consuming_systems_implementation_statements method to force synchronize implementation statements of consuming systems; and
Added an elements/synchConsumingSystemsImplementationStatements API v2 endpoint to trigger component to system synchronization via the API.
Updating a component via the v2 API involves a two step process.
First, call the element/createOSCAL endpoint with the new OSCAL component definition and the update parameter set to true. This will make the API update an existing component that matches by title (e.g., name) of the component if one exists. Setting update to true will update the component that matches by name instead of creating a new component. Updating the component means that the component in the library will have its statements updated, new statements added, and removed statements deleted. The elements/createOSCAL endpoint only effects the component library, and not any of the control implementation statements associated with the component on individual systems. The updated OSCAL adds, removes, and updates statements.
Second, call the elements/synchConsumingSystemsImplementationStatements endpoint using the component's ID in the database to synchronize the statements in the consuming systems. This API endpoint can be used at anytime to force synchronize The Element.synch_consuming_systems_implementation_statements method is called by the API. This enables the synchronization to be done.
The released implementation force updates the component definition of all consuming systems.
Note that the update and synchronization method are compatible with maintaining a change history of each statement. However, a deleted statement and its history will simply disappear. There history of a statement being deleted.
Using
Use the Swagger API to test:
/api/v2/docs/swagger/ > elements/createOSCAL
/api/v2/docs/swagger/ > elements/synchConsumingSystemsImplementationStatements
## Future improvements
- [ ] Check if user has permission to update an existing component
- [ ] Enable a flag on individual systems to not accept updates from component
- [ ] Match on component UUID or component title and not just component database ID
- [ ] Update status (e.g., implemented, not implemented, etc.) of each statement
- [ ] Update pid of control implementation statement
- [ ] Check if multiple statements associated with same system and same control id are correctly handled
- [ ] Provide more granular report of changes (e.g., statements changed, statements added, statements removed, etc.)
- [ ] Update statement changelog with each change
- [ ] Create a UI to trigger `Element.synch_consuming_systems_implementation_statements`
Stories
As an administrative user, I want to be able to update an existing component's description and implementation statements via the API so that I can maintain a component definition outside of GovReady-Q and automatically update component definition in GovReady-Q.
As an administrative user, I want to be able to propagate a change in a component's implementation statements to all all systems using that component, so that if I update a component definition I can have all systems consuming that component have their statements updated, too.
Update various Python and NPM libraries.
Discussion
Three changes were made to support updating components:
updateboolean parameter to theelements/createOSCALAPI v2 endpoint to indicate an existing component should be updated;Element.synch_consuming_systems_implementation_statementsmethod to force synchronize implementation statements of consuming systems; andelements/synchConsumingSystemsImplementationStatementsAPI v2 endpoint to trigger component to system synchronization via the API.Updating a component via the v2 API involves a two step process.
First, call the
element/createOSCALendpoint with the new OSCAL component definition and theupdateparameter set to true. This will make the API update an existing component that matches by title (e.g., name) of the component if one exists. Settingupdateto true will update the component that matches by name instead of creating a new component. Updating the component means that the component in the library will have its statements updated, new statements added, and removed statements deleted. Theelements/createOSCALendpoint only effects the component library, and not any of the control implementation statements associated with the component on individual systems. The updated OSCAL adds, removes, and updates statements.Second, call the
elements/synchConsumingSystemsImplementationStatementsendpoint using the component's ID in the database to synchronize the statements in the consuming systems. This API endpoint can be used at anytime to force synchronize TheElement.synch_consuming_systems_implementation_statementsmethod is called by the API. This enables the synchronization to be done.The released implementation force updates the component definition of all consuming systems.
Note that the update and synchronization method are compatible with maintaining a change history of each statement. However, a deleted statement and its history will simply disappear. There history of a statement being deleted.
Using
Use the Swagger API to test: