Table of Contents

Registering a new version of a multi-artifact DataMiner package to the Catalog using Visual Studio and GitHub

In this tutorial, you will learn how to develop, (pre-)release, and upload a DataMiner package to the Catalog with a basic CI/CD pipeline using Visual Studio and GitHub. This package will contain multiple artifacts:

  • Automation script: TutorialScript1
  • Automation script: TutorialScript2
  • Automation script library: TutorialLibrary
  • Ad hoc data source: TutorialDataSource

The package will include a simple .txt file that will be read out during installation, generating an information event with the information from the file.

Expected duration: 15 minutes

Prerequisites

Overview

Step 1: Add code-based content

Start by adding all code-based content into a Visual Studio solution:

  1. Create a DataMiner package project:

    1. Open Visual Studio, and select Create a new project.

    2. Select the DataMiner Package Project template, and click Next.

    3. Enter the project name TutorialPackage.

    4. Make sure Place solution and project in the same directory is not selected, and click Next.

    5. Fill in your name as the author and keep Create DataMiner Package selected.

    6. Under Add GitHub CI/CD Workflow (Overwrite Existing), select Demo.

    7. Click Create.

  2. Add a first DataMiner automation script project:

    1. In the Solution Explorer, at the very top, right-click the solution TutorialPackage and select Add > new project.

    2. Select the DataMiner Automation Script Project template, and click Next.

    3. Enter the project name TutorialScript1.

    4. Fill in your name as the author and make sure Create DataMiner Package is not selected.

    5. Under Add GitHub CI/CD Workflow (Overwrite Existing), keep the default None selected.

    6. Click Create.

  3. Add a second DataMiner automation script project:

    1. In the Solution Explorer, at the very top, right-click the solution TutorialPackage and select Add > new project.

    2. Select the DataMiner Automation Script Project template, and click Next.

    3. Enter the project name TutorialScript2.

    4. Fill in your name as the author.

    5. Click Create.

  4. Add a DataMiner automation script library project:

    1. In the Solution Explorer, at the very top, right-click the solution TutorialPackage and select Add > new project.

    2. Select the DataMiner Automation Script Library Project template, and click Next.

    3. Enter the project name TutorialLibrary.

    4. Fill in your name as the author.

    5. Click Create.

  5. Add a DataMiner ad hoc data source project:

    1. In the Solution Explorer, at the very top, right-click the solution TutorialPackage and select Add > new project.

    2. Select the DataMiner Ad Hoc Data Source Project template, and click Next.

    3. Enter the project name TutorialDataSource.

    4. Fill in your name as the author.

    5. Click Create.

Step 2: Add installation-specific code

In this step, you will focus on the extra code that should be executed when the content is installed.

  1. Add the setup content:

    1. In the Solution Explorer, navigate to the project TutorialPackage and right-click the SetupContent folder.

    2. Select Add > New Item.

    3. Select to add a new text file (.txt), and give it the name MyConfig.txt.

    4. Write Hello World! as the content and save the file.

  2. Write the installation code:

    1. In the Solution Explorer, navigate to the project TutorialPackage and double-click to open the TutorialPackage.cs file.

    2. Change the content of the Install method to the following:

         try
   {
      engine.Timeout = new TimeSpan(0, 10, 0);
      engine.GenerateInformation("Starting installation");
      var installer = new AppInstaller(Engine.SLNetRaw, context);
      installer.InstallDefaultContent();

      string setupContentPath = installer.GetSetupContentDirectory();

      // Custom installation logic can be added here for each individual install package.
      string pathToConfig = System.IO.Path.Combine(setupContentPath, "MyConfig.txt");
      var config = System.IO.File.ReadAllText(pathToConfig);
      engine.GenerateInformation($"Tutorial installation ran with config: {config}");
   }
   catch (Exception e)
   {
      engine.ExitFail($"Exception encountered during installation: {e}");
   }

    3. Save the changes

Step 3: Create a GitHub repository

  1. In the menu bar of Visual Studio, select GIT > Create GIT Repository.

  2. Create a new GitHub repository:

    1. Select a name, specify your GitHub account, and mark yourself as the owner.

    2. When you have entered all the information, click Create and Push.

  3. Go to the newly created GitHub repository on https://github.com/.

    Tip

    In Visual Studio 2022, you can open the GIT menu and select GitHub/View Pull Requests to quickly access the correct repository.

Step 4: Check the GitHub Actions

  1. In GitHub, go to the Actions tab.

  2. Click the workflow run that failed (usually called Add project files).

  3. Click the "build" step that failed and read the failing error.

    Error: DATAMINER_TOKEN is not set. Release not possible!
Please create or re-use an admin.dataminer.services token by visiting: https://admin.dataminer.services/.
Navigate to the right organization, then go to Keys and create or find a key with the permissions Register catalog items, Download catalog versions, and Read catalog items.
Copy the value of the token.
Then set a DATAMINER_TOKEN secret in your repository settings: <Dynamic Link>

    You can use the links from the actual error in the next couple of steps.

Step 5: Create and add a secret

  1. Obtain an organization key from admin.dataminer.services with the required scopes:

    • Register catalog items
    • Read catalog items
    • Download catalog versions
    Tip

    See also: dataminer.services keys

  2. Add the key as a secret in your GitHub repository, by navigating to Settings > Secrets and variables > Actions and creating a secret named DATAMINER_TOKEN.

  3. Re-run the workflow.

With this setup, any push with new content (including the initial creation) to the main/master branch will generate a new pre-release version, using the latest commit message as the version description.

Step 6: Check the results

  1. Go to the Catalog

  2. Check in the upper-right corner if the correct organization is selected.

  3. Search for the name of your package.

    By default, this is your Visual Studio project name (e.g., TutorialPackage).

  4. Go to the VERSIONS tab.

    This tab should contain the new version of the package, which is now available for deployment from the Catalog.

  5. If you have an available non-production DataMiner Agent, use the Deploy button to deploy the new version to the DMA.

    All artifacts will be installed. In DataMiner Cube, you should see an information event in the Alarm Console saying Tutorial installation ran with config: Hello World!.

Improve this page