Walkthrough: Managing versions of NSH scripts using Git

This topic walks you through the use of Git for version management of NSH scripts. It includes the following sections:

The video at right demonstrates the various tasks involved in version management of NSH scripts using Git.


https://docs.bmc.com/docs/plugins/servlet/confluence/placeholder/unknown-attachment?locale=en_GB&version=2 https://youtu.be/lW7fHYMJnBM


Introduction

This topic is intended for system administrators or operators who are responsible for the creation, modification, and use of NSH scripts in TrueSight Server Automation.

The goal of this topic is to use an integration with Git for version management tasks, such as keeping track of revisions, comparing revisions, or reverting to an earlier revision .

What does this walkthrough show?

This walkthrough shows how to use Git for version management of NSH scripts. The walkthrough includes the following tasks:

  • Migrating existing NSH scripts to a local repository. 
  • Choosing the option for storage in the local Git repository while adding a new NSH script to the depot.
  • Committing revisions of an NSH script to the local repository.
  • Reviewing a history of revisions in an NSH script, including information regarding who made each change and when.
  • Comparing revisions of an NSH script.
  • Reverting to an earlier version of an NSH script.
  • Pushing all committed revisions of an NSH script to the remote Git repository.

What do I need to do before I get started?

Before you can manage versions of NSH scripts, ensure that you have set up a local repository in the TrueSight Server Automation environment, as well as the remote Git repository. For more information about these setup tasks, see Setting-up-Git-repositories.

For this walkthrough, we have logged on as BLAdmin, the default superuser for BSA.



How to migrate existing NSH scripts to the local repository

In this example, TrueSight Server Automation was only recently integrated with a Git repository, and many NSH scripts in the depot were created prior to the integration. These NSH scripts were saved in the file server, rather than the local Git repository, and do not support version management. To enable version management for such NSH scripts, you can migrate them from the file server to the local Git repository either individually or in bulk. First let's move one NSH script to the repository and examine how this migration changes script settings.

Note

To perform this migration task through the BLCLI (as an alternative to the GUI method described here), you can use the NSHScript moveToGit command.


Step

Example screen

1

Under the Depot folder, navigate to an NSH script that was created some time ago (before you set up the Git integration), and open it.

nonMigrated.png

2

In the open NSH script, note that only 3 tabs are displayed (Script Options, Script, and Parameters).

In addition, on the Script Options tab, note that the Repository Type field is set to BSA Repository and is not editable.

Now close the NSH script.

beforeMigration.png

3

Right-click the NSH script again in the tree, and choose Move to Git.

migrationAction.png

4

In the confirmation message, click Yes.

migrationConfirmation.png

5

Now, when you open the NSH script, the Repository Type field on the Script Options tab is set to Git Repository (still not editable).

In addition, a fourth tab is displayed, Git Repository History. On this tab, you see that the NSH script was immediately committed to the local Git repository, with the message "Migration to Git from Fileserver - First Commit..."

afterMigration.png

migrationCommit.png

Now let's move multiple NSH scripts to the repository, all at once, through the Group Explorer view.


Step

Example screen

1

From the main menu, select Window > Show View > Group Explorer.

groupExplorer.png

2

Under the Depot folder, click a folder that contains multiple unmigrated NSH scripts.
The contents of the folder appear in the Group Explorer view.

bulkMigration.png

3

 Select multiple unmigrated NSH scripts, right-click, and choose Move to Git.

4

In the confirmation message, click Yes.

migrationConfirmation.png

5

The Git-Migration-Result-dialog-box displays the results of the migration.
Ensure that all items were migrated successfully.

migrationResults.png

How to save a new script and commit it into the local Git repository

In this example, we will add an NSH script to the depot and set it to be saved in the local Git repository (rather than in the file server), so that we can control the versions of this NSH script in the future. We will then commit the initial version of the script to the local Git repository.

Note

To perform this task through the BLCLI (as an alternative to the GUI method described here), you can use the NSHScript addNSHScriptToExternalRepo command followed by the NSHScript commitNSHScript command. You use the addNSHScriptToExternalRepo command when you want to enable version management for a new NSH script, as opposed to the addNSHScriptToDepotByGroupName command, which you use when you do not want to enable version management.


Step

Example screen

1

Under the Depot folder, right-click the folder in which you want to store the NSH script, and select New > NSH Script.

addScript.png 

2

In the Add NSH Script to Depot wizard (on the Script Options panel), enter a name for the script in the Name field, and specify the location of the script in the File Location field.

Then, in the Repository Type field, select Git Repository (this is the default option).

Note

If you choose the BSA repository option while adding the NSH script to the depot, the only way to subsequently switch to the Git Repository option and enable version management for the NSH script is to migrate the NSH script to the Git repository.

Finally, click Finish.

The NSH script is added to the folder. You might need to refresh the folder to see the newly added script.

scriptWizard.png

3

Navigate to the newly added NSH script, right-click it, and select Open.

openScript.png

4

Click the Git Repository History tab.

The list of script revisions contains one entry with the commit message "Uncommitted changes exist."

history_for_new.png

5

Click the Commit button commitButton.png above the list.

6

In the Git Commit dialog box, adjust the email address and enter a summary message to accompany the commit.

Afterwards, click Commit and then click OK in the informational message.

commitSuccess_new.png

7

Take another look at the list on the Git Repository History tab. The initial entry now has commit details.

committedNew.png

How to commit changes to a script


The example script that we just added to the depot collects various statistics from a target server's operating system and generates a report on a reporting server. However, the IP address of the reporting server is hard-coded within the script. We will now edit this IP address, to switch to a different reporting server. We will also add a new script parameter named TEST. We will then commit the change to the local Git repository.

Note

To perform the commit task through the BLCLI (as an alternative to the GUI method described here), you can use the NSHScript commitNSHScript command. 

After upgrading to TrueSight Server Automation 8.9, various issues might arise in the Git version management of existing, pre-upgrade NSH scripts. To avoid such issues, perform an initial commit of each existing NSH script before performing any further actions on the script (such as changing script parameters or reverting to an earlier revision). For this initial commit action, use the following steps:

  1. Make a small change in the script text. This change can be any dummy edit, such as adding a comment line.
  2. Commit the script, as described below.


Step

Example screen

1

In the open script, click the Script tab. Then make a change within the script text.

In this example, we will set new values for the REPORTS_SERVER and REPORTS_DIR parameters.

After editing the script text, save the NSH script using the Save button save.png in the toolbar.

editScript.png

2

Click the Parameters tab. To add a new parameter to the script, click the Add Parameter addParameter.png icon, and then, in the Add Parameter dialog box, enter a name for the parameter (in this example, we named the parameter TEST), and click OK.

Remember to save the NSH script using the Save button save.png in the toolbar.

newPrm.png

3

Click the Git Repository History tab.

A new entry appears in the list of script revisions, with the commit message "Uncommitted changes exist."

Note

If this commit message does not appear (typically, after a product upgrade, due to upgrade issues), click the Refresh button refreshIcon.png above the list.

history1.png

4

Click the Commit button commitButton.png above the list.

5

In the Git Commit dialog box, adjust the email address and enter a summary message to accompany the commit.

Afterwards, click Commit and then click OK in the informational message.

Commit details for the new revision are added on the Git Repository History tab.

commitSuccess_changed89.png


How to compare script revisions and revert to a previous revision

The list of changes in the script contains already two entries. We will compare the two versions and revert to the earlier version of the script.


Step

Example screen

1

In the open script, on the Git Repository History tab, review the various entries listed in the history of script changes.

Each entry provides commit details, including the commit message, the name of the user who made the change, and the date and time when the change was made.  

history2.png

2

Select the two script revisions and click Compare compareButton.png.

compareHistory.png

3

Two new tabs appear in the editor — one with a comparison of the script contents and the other with a comparison of the script parameters (in json format).

On each tab, the comparison opens directly to the first difference between the two versions. The newer version is on the left and the older version on the right.

To navigate to other differences, use the Next Change nextChange.png and Previous Change prevChange.png buttons above the compared text.

comparisonScript.png

comparisonPrms.png

4

After reviewing the differences, we have decided to revert to the original version of the script.

To revert, return to the open script, select the version of the script to which you want to revert, and click Get This Revision revertButton.png.

reverting.png

5

In the confirmation message, click Yes.

revertConfirmation89.png

6

A new change entry is added to the script history. To finish reverting to the earlier version of the script, you must commit this change. Click Commit commitButton.png.

AfterRevert.png

7

In the Git Commit dialog box, adjust the email address and enter a summary message to accompany the commit for the revert.

Afterwards, click Commit and then click OK in the informational message.

commitAfterRevert.png

8

Commit details for the new revision are added on the Git Repository History tab.

afterRevertAndCommit.png

Note

Any versions of the NSH script that were committed to the repository before upgrading to TrueSight Server Automation 8.9 will not have parameter information stored. For such script versions, a comparison of parameters is not generated. Similarly, when reverting to such a version of the script, the parameters are not reverted.


How to push all changes to the remote Git repository

You must periodically push all changes stored in the local Git repository to the remote Git repository.

Note

 To perform this task through the BLCLI (as an alternative to the GUI method described here), you can use the Git pushToRemote command.


Step

Example screen

1

In the console, click the Push button pushButton.pngin the toolbar.


pushing.png

2

The Git-Push-dialog-box displays information about all commits that will be pushed to the remote Git repository.

Click Push.

pushBox.png

3

Click OK in the informational message.

pushSuccess.png

Wrapping it up

Congratulations! You have successfully performed version management on an NSH script.

Now that you are actively managing changes in NSH scripts, you can choose any previous version of a script to associate with a Network Shell Script Job, during creation or modification of the Network Shell Script Job.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*