Table of Contents

Registering a new version of a user-defined API to the Catalog using Visual Studio and GitHub

In this tutorial, you will learn how to develop, (pre-)release, and upload a user-defined API to the Catalog with a CI/CD pipeline using Visual Studio and GitHub. However, note that you can use similar steps for any artifact type except for connectors (e.g., automation script, automation script library, package project, etc.).

Expected duration: 10 minutes

Prerequisites

Overview

Step 1: Create a Visual Studio project

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

  2. Select the DataMiner User-Defined API Project template, and click Next.

  3. Enter a project name, for example MyUserDefinedApi.

  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.

Step 2: 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 3: 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/find a key with permissions to 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 4: 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 by going back to the failing run and selecting Re-run jobs in the upper-right corner.

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 5: 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., MyUserDefinedApi).

  4. Go to the VERSIONS tab.

    This tab should contain the new version of your user-defined API, which is now available for deployment from the Catalog.

Improve this page