Skyline DataMiner Package Project

The Skyline DataMiner Package Project is designed to create multi-artifact packages in a straightforward manner.

Note that the information below assumes that you have access to Visual Studio and DIS. However, for most of what is mentioned below there is also limited support for Visual Studio Code without DIS. Only importing from DataMiner can only be handled by DIS at present.

Creating a DataMiner application package

The project is by default configured to create a .dmapp file every time you build the project.

When you compile or build the project, you will find the generated .dmapp in the standard output folder, which is typically the bin folder of your project.

When you publish the project, a corresponding item will be created in the online DataMiner Catalog.

Adding extra artifacts in the same solution

New artifacts

You can right-click the solution and select Add > New Project. This will allow you to select DataMiner project templates (e.g. to add additional Automation scripts).

Note

Connectors are currently not supported for this.

You can also add new projects by using the dotnet-cli. For the sake of stability, we recommend always using an sln solution with all projects included.

    dotnet new sln
    dotnet new dataminer-user-defined-api-project -o MyUserDefinedApiFromGithub -auth MyName
    dotnet sln add MyUserDefinedApiFromGithub

Every Skyline.DataMiner.SDK project within the solution, except other DataMiner package projects, will by default be included within the .dmapp created by this project. You can customize this behavior using the PackageContent/ProjectReferences.xml file. This allows you to add filters to include or exclude projects as needed. See ProjectReferences.xml for more information.

Existing Automation script files

You can right-click the solution and select Add > Add Existing DataMiner Automation Script. This will allow you to add existing Automation scripts files to the solution.

Importing from DataMiner

You can import specific items directly from a DataMiner Agent using DIS:

In Visual Studio, connect to an Agent via Extensions > DIS > DMA > Connect.
If your Agent is not listed, add it by going to Extensions > DIS > Settings and clicking Add on the DMA tab.
Once connected, import the DataMiner artifacts you want:
- To import dashboards:
  1. In your Solution Explorer, navigate in the Package project to PackageContent/Dashboards.
  2. Right-click, and select Add.
  3. Select Import DataMiner Dashboard.
- To import low-code apps:
  1. In your Solution Explorer, navigate in the Package project to PackageContent/LowCodeApps.
  2. Right-click, and select Add.
  3. Select Import DataMiner Low-Code App.
- To import an Automation script:
  1. In your Solution Explorer, right-click the solution, and select Add.
  2. Select Import DataMiner Automation Script.

Adding content from the Catalog

You can reference and include additional content from the Catalog using the PackageContent/CatalogReferences.xml file provided in this project. See CatalogReferences.xml for more information.

For the SDK to be able to download the referenced items from the Catalog, configure a user secret in Visual Studio:

Obtain an organization key from admin.dataminer.services with the following scopes:
- Register catalog items
- Read catalog items
- Download catalog versions
Securely store the key using Visual Studio User Secrets:
1. Right-click the project and select Manage User Secrets.
2. Add the key in the following format:
```
{ 
  "skyline": {
    "sdk": {
      "dataminertoken": "MyKeyHere"
    }
  }
}
```

Executing additional code on installation

Open the $SCRIPTNAME$.cs file to write custom installation code. Common actions include creating elements, services, or views.

Tip

Type clGetDms in the .cs file and press Tab twice to insert a snippet that gives you access to the IDms classes, making DataMiner manipulation easier.

Adding configuration files

If your installation code needs configuration files (e.g. .json, .xml), you can add these to the SetupContent folder, which can be accessed during installation.

Access them in your code using:

string setupContentPath = installer.GetSetupContentDirectory();

Publishing to the Catalog

By default, a project is created with support for publishing to the DataMiner Catalog. You can publish your artifact manually through Visual Studio or by setting up a CI/CD workflow.

Publishing manually

Obtain an organization key from admin.dataminer.services with the following scopes:
- Register catalog items
- Read catalog items
- Download catalog versions
Securely store the key using Visual Studio User Secrets:
1. Right-click the project and select Manage User Secrets.
2. Add the key in the following format:
```
{ 
  "skyline": {
    "sdk": {
      "dataminertoken": "MyKeyHere"
    }
  }
}
```
Publish the package by right-clicking your project in Visual Studio and then selecting the Publish option.

This will open a new window, where you will find a Publish button and a link where your item will eventually be registered.

Note

To safeguard the quality of your product, consider using a CI/CD setup to run dotnet publish only after passing quality checks.

Changing the version of a package

There are two ways to change the version of a package:

By adjusting the package version property:
1. Navigate to your project in Visual Studio, right-click, and select Properties.
2. Search for Package Version.
3. Adjust the value as needed.
By adjusting the Version XML tag:
1. Navigate to your project in Visual Studio and double-click it.
2. Adjust the Version XML tag to the version you want to register.
```
<Version>1.0.1</Version>
```

Publishing to the Catalog with the basic CI/CD workflow

If you have used the Skyline.DataMiner.VisualStudioTemplates, your project can include a basic GitHub workflow for Catalog publishing.

Follow these steps to set it up:

Create a GitHub repository by going to Git > Create Git Repository in Visual Studio, selecting GitHub, and filling in the wizard before clicking Create and Push.
In GitHub, go to the Actions tab.
Click the workflow run that failed (usually called Add project files).

Click the "build" step that failed and read the 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 permission 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 to better address the next couple of steps.

Obtain an organization key from admin.dataminer.services with the following scopes:
- Register catalog items
- Read catalog items
- Download catalog versions
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.
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.

Releasing a specific version

Navigate to the <> Code tab in your GitHub repository.
In the menu on the right, select Releases.
Create a new release, select the desired version as a tag, and provide a title and description.

Note

The description will be visible in the DataMiner Catalog.

Publishing to the Catalog with the complete CI/CD workflow

If you have used the Skyline.DataMiner.VisualStudioTemplates, your project can include a complete GitHub workflow for Catalog publishing. This comprehensive GitHub workflow adheres to Skyline Communications' quality standards, including static code analysis, custom validation, and unit testing.

Make sure you have a SonarCloud organization.

If you do not have one yet, you can create it on sonarcloud.io.
Create a GitHub repository by going to Git > Create Git Repository in Visual Studio, selecting GitHub, and filling in the wizard before clicking Create and Push.
In GitHub, go to the Actions tab.
Click the workflow run that failed (usually called Add project files).

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 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 to better address the next couple of steps.

Obtain an organization key from admin.dataminer.services with the following scopes:
- Register catalog items
- Read catalog items
- Download catalog versions
Add the key as a secret in your GitHub repository, by navigating to Settings > Secrets and variables > Actions and creating secrets or variables with the required names.
Re-run the workflow.

The following secrets and variables will have been added to your repository after all issues are resolved:

Name	Type	Description	Setup Guide
`DATAMINER_TOKEN`	Secret	Organization key for downloading/publishing from/to the Catalog	Obtain from admin.dataminer.services and add it as a secret.
`SONAR_TOKEN`	Secret	Token for SonarCloud authentication	Obtain from SonarCloud Security and add it as a secret.
`SONAR_NAME`	Variable	SonarCloud project ID	Visit SonarCloud, copy the project ID, and add it as a variable.

Releasing a version

Navigate to the <> Code tab in your GitHub repository.
In the menu on the right, select Releases.
Create a new release, select the desired version as a tag, and provide a title and description.

Note

The description will be visible in the DataMiner Catalog.

Table of Contents

Skyline DataMiner Package Project

Creating a DataMiner application package

Adding extra artifacts in the same solution

New artifacts

Note

Existing Automation script files

Importing from DataMiner

Adding content from the Catalog

Executing additional code on installation

Tip

Adding configuration files

Publishing to the Catalog

Publishing manually

Note

Changing the version of a package

Publishing to the Catalog with the basic CI/CD workflow

Releasing a specific version

Note

Publishing to the Catalog with the complete CI/CD workflow

Releasing a version

Note

See also