IBM DNG Working Method
- Tino Pförtner
Prerequisites: access to a central repository and a MySQL database installation.
SOX-DNG Connection Setup
You will receive from EnCo a “properties” file which can be edited in order to configure your server. The properties file supplements the read-only configuration file, supplied as a compressed archive, that also needs to be deployed on your server. In the current configuration, user credentials are “hard-saved” server-side, although this may be subject to change in future releases. I.e., the properties file allows the customer to nominate one DNG user, with his associated password, who will then have access to the external (DNG) repository. This user is not required to be a physical person; it could be an entity generically named “SOX Synchronization” or suchlike, with the implication that this entity may subsume multiple, and varying, users of the SOX rich client. As such, the credentials used authenticate a systemic identity, rather than a personal one.
It will also be possible to edit as required details like the DNG server’s port number (its IP address seems unlikely to change). This setup will enable the SOX server to connect to the DNG server.
Video Tutorial
See below for a visualization of the synchronization process.
Configure Synchronization
Initiate the process by right-clicking your project. Select Configure Synchronization:
Outcome: the Editor will display the synchronization file associated with your project.
Right-click on the single entry and select New Child. The choices shown result from actual queries of the DNG installation. Our example uses the DNG project “English”.
Outcome: the project chosen will appear in the Editor window.
Next, query the Shapes (artifact types) in your DNG project in order to import Shape Definitions. This is done by right-clicking on your project, our example being project “English” once again.
Outcome: SOX will initiate a server-side query (in technical terms, the SOX server will query the DNG server). The SOX client will then display the results, i.e., the complete set of Instance Shapes (artifact types) found in DNG. SOX can now work on any property structure defined for a given artifact type. Expressed differently, the data structure definition established DNG-side will now be available for working on with the SOX interface.
You can now open the drill-down list to review any field/property definition.
For example, it is possible to examine and, where appropriate, change a given Field Type.
Next, there exists an option to create a new Group Definition, corresponding to a DNG module (i.e., a logical, hierarchical container for requirements). Do this by right-clicking your DNG project and selecting New Child > Group Definition.
In the SOX context, a Group references a ReqIF document. This setup achieves synchronization of a SOX specification document with a DNG module. Select your Document Path, as well as the Query Executor “Module”. The Query String needs to match the module identifier (number) used in DNG, in the example scenario, “385”.
Lastly, you will need to create default Item Definitions. To accomplish this, right-click the Safety Group Definition (corresponding to a Doors Module) and select New Child - Import Item Definitions. - Outcome: SOX will query the specified DNG module in order to determine which artifact types are present in the relevant requirements subset. These will be displayed accordingly.
Further properties can then be modified as required.
This activity completes the configuration process.
Use good judgment to decide which changes to your field types are appropriate in a specific context. Some changes, although technically possible, may yield unexpected results or errors. Most defaults are adequate and should, hence, not be modified.
Synchronizing Your Project
It is now possible to initiate the synchronization process. As an initial phase, you may wish to perform a Dry Run. So doing will serve the twofold purpose of familiarizing yourself with the process and interface, as well as validating your configuration settings. To achieve these objectives, right-click your SOX project and choose Synchronize (Dry Run).
Outcome: The Synchronization dialog will open.
As is evident from the menu, you have the alternative options of importing data vs. synchronizing existing data. In the context of the Dry Run, this selection is of little relevance, as the system will not really action any data transfer in either scenario. Click OK to start the process.
If, for example, you intend to export back changes to a manifest change set, you will need to supply the set’s URI here. The Global Configuration Context will be used by default if nothing is specified here.
Outcome: if there were no errors, SOX will report success.
If the Dry Run was performed successfully, you are ready to proceed with the actual synchronization. Once again, right-click your project; this time around, select Synchronize:
Outcome: the synchronization dialog will open as demonstrated before:
Again, one’s choice of Synchronization direction is immaterial if doing the process for the first time, aiming to bring the DNG data into SOX for possible modification. - Subsequent to confirmation with OK, SOX will commence synchronizing itself with the remote server. Note that depending on parameters like volume and transfer rate, the initial synchronization may take a number of minutes, since this performance involves some internal computation. Syncing repeated within the same session should be notably faster.
Outcome: if the Dry Run succeeded, the Synchronization is likely to complete successfully also. Hence, SOX will report success, and the Module requirements will have been loaded from DNG. A new document (a ReqIF specification) will have been created and will be available for editing and backwards synchronization. As noted, the initial structure will be identical to the one synchronized with, or imported from, DNG-side.
Double-clicking the root node will open the ReqIF editor:
When synchronizing backwards any changes/additions to your data, you will be prompted for the target change set.
Synchronization: Method and Example Walkthroughs
There now follows a brief example walkthrough of synchronizing SOX and a DNG system with one another. Our raw material is the module synchronized with in the above demonstration.
SOX to DNG
Note in the screenshot below that the Hazard bears the idiosyncratic name “Lyo Never Rocks”.
We edit this in SOX to read “Lyo Never Ever Rocks” and synchronize once again, using the established method.
The Statistics pop-up confirms that we made one modification:
If next we locate the relevant Hazard on the DNG system, we can confirm that the change became effect, i.e., migrated from SOX to DNG consequent to our synchronization:
DNG to SOX
Our starting point is a Hazard that in DNG - and, by implication, in SOX - is originally titled “Sharp Edges”:
We edit the name to make the title “Really Sharp Edges” and synchronize yet again. Subsequent to this performance, SOX displays our modification:
Configuration Management Enabled Projects
This feature introduces a new type of project based on configurable components. Each configuration of each component is able to figure as an external project within the overall configuration. The general logic of interacting with the DNG interface remains the same.