MindConnect-NodeJS - Contributing

We welcome contributions in several forms, e.g.

  • Sponsoring
  • Documenting
  • Testing
  • Coding
  • etc.

Please check for the issues in the project and look for unassigned ones or create a new one. The good issues for newcomers are marked with help-wanted and good-first-issue.

Working together in an open and welcoming environment is the foundation of our success, so please respect our Code of Conduct.

Contributing to MindSphere TypeScript SDK

If you want to contribute with a new Client Implementation to typescript SDK here are some guidelines

1. Create Issue

Tell the community that you are working on an client :)

2. Create the file structure

client and models:

\src\api\sdk\<yourapi>\
                        <yourapi>.models.ts
                        <yourapiclient>.ts

tests:

\test\
        <yourapiclient>.spec.ts

cli command(s):

\src\cli\commands folder

Just follow the existing code examples ;)

3. Generate the Models

You can generate the models form OpenAPI specification using. e.g. https://editor.swagger.io and typescript-fetch template. The models belong into the namespace called <yourapi>Models

export namespace TimeSeriesAggregateModels {
....models go here
}

4. Implement the Client, Tests and CLI commands

Implement the client for your API using this.HttpAction method and following the existing conventions. Using HttpAction ensures that the API Client works with different authorizers. Here is an example for TimeSeriesAggregateClient:

// Always extend SdkClient, this will give you access to this.HttpAction
export class TimeSeriesAggregateClient extends SdkClient {
  // base Url from OpenAPI specification
  private _baseUrl: string = "/api/iottsaggregates/v3";

  // the path parameters belong in the function parameters and the querystring parameters in params object
  public async GetAggregates(
    entityid: string,
    propertyset: string,
    params: {
      from: Date;
      to: Date;
      intervalValue: number;
      intervalUnit: string;
      select?: string;
    }
  ): Promise<TimeSeriesAggregateModels.Aggregates> {
    const qs = toQueryString(params);
    return (await this.HttpAction({
      verb: "GET",
      gateway: this.GetGateway(), // always use this.GetGateway()  and this.GetToken()
      authorization: await this.GetToken(), //this is overriden in different authorizers
      //and ensures that the Client works in frontend and in backend.
      baseUrl: `${this._baseUrl}/aggregates/${entityid}/${propertyset}?${qs}`,
      message: "GetTimeSeriesAggregates", // this is used for logging
    })) as TimeSeriesAggregateModels.Aggregates; // always cast to the real result type from models
  }
}

You also have to create a Method for lazy loading of your new client on the MindSphereSdk class

private _timeSeriesAggregateClient?: TimeSeriesAggregateClient;

public GetTimeSeriesAggregateClient(): TimeSeriesAggregateClient {
    this._timeSeriesAggregateClient =
        this._timeSeriesAggregateClient || new TimeSeriesAggregateClient(this._authenticator);
    return this._timeSeriesAggregateClient;
}

and add export to src\api\sdk\index.ts file:

...
export * from "./iotaggregate/iot-timeseries-aggregate";
export * from "./iotaggregate/iot-timeseries-aggregate-models";
...

make sure that the tests are running and create a pull request. We would also really appreciate a CLI contribution.

Guidelines

Workflow

We use the Feature Branch Workflow and review all changes we merge to master.

Automated builds, tests, security and code quality checks

The code is required to pass the automated build, all unit-tests must be green and the configured security- (snyk) and code quality (lgtm) checks must be OK before the pull request can be merged.

Commit Message

Commit messages shall follow the conventions defined by conventional-changelog.

What to use as scope

In most cases the changed component is a good choice as scope e.g. if the change is done in the MindConnectAgent the scope should be Agent.

Code Style

Please follow the typescript code style which is established in tslint.json. (Works out of the box in many editors, e.g. Visual Studio Code)

Setting up the local development environment

You will need a MindSphere Account to setup the development environment. If you don’t have an account yet, you can register here for a free account. (that is free as in a beer :)

Executing unit tests

The unit tests require the configured service credentials and a 3072 bit agent certificate.

First: install the library and CLI globally and run the create service credentials command

# install the cli
npm install -g @mindconnect/mindconnect-nodejs

# create service credentials
mc service-credentials

# mc service-credentials --help will provide more help (you can use app credentials or service credentials)

Setting up the MindSphere CLI

after that you will need a 3072 bit certificate

# run only once to create certificate
npm run createkey

You are now all set and should be able to run the unit tests locally. Please note that not all tests will run on your machine if you have a start-for-free account due to MindSphere restrictions.

npm run test

Local Development Scripts

Developing new features and unit tests npm run dev

The npm run dev command will start the typescript transpiler and mocha unit testing in a watch mode so that you can add new features to the library.

Developing new CLI Commands npm run ts:watch

Start in one shell npm run ts:watch to run the typescript transpiler in the watch mode. You can run the command you are developing with:

node src/cli/mc [list of parameters...]

A useful shortcut is to create an alias in your shell for this:

alias lmc='node src/cli/mc'

Running the commands is now very similar to the installed version but instead of mc command [options] you will use lmc command [options], for example like this:

lmc list-assets

Don’t forget to start another shell with npm run ts:watch which runs the typescript transpiler.

package.json scripts

npm run clean

Deletes dist/, starterts/ and starterjs directory.

npm run clean:dist

Deletes dist/ directory.

npm run prepare

Prepares the library for installation. It is called by npm pack and npm install commands.

The script executes following steps:

  • cleans the dist/ directory (npm run clean)
  • transpiles the typescript code to dist/ directory (npm run ts:build)
  • copies the html files for mc service-credentials command to dist/ directory (npm run copyfiles:dist)
  • executes the webpack build for the browser distribution of the SDK (npm run browser:build)

npm run copyfiles:dist

copies the html files for mc service-credentials command to dist/ directory. This script is usually only called from the prepare script.

npm run test

Transpiles the typescript and runs the mocha unit test suite

npm run test-dev

Transpiles the typescript and runs the mocha unit test suite with NODE_TLS_REJECT_UNAUTHORIZED=0 so that you can inspect the HTTP traffic e.g. by using Telerik Fiddler as a proxy server.

npm run test-jenkins

Called by jenkins to create test resports in CI/CD pipeline.

npm run ts:build

Run the typescript transpiler.

npm run ts:build:dist

Run the typescript transpiler and save results in dist/ folder. (used by prepare script)

npm run ts:watch

Run typescript transpiler in watch mode (used for development)

npm run lint

Start typescript linter

npm run dev

Local development for new features. Runs concurrently typescript transpiler in watch mode (npm run ts:watch) and mocha in watch mode (npm run test:watch)

npm run doc

Generates the documentation.

npm run createkey

Creates a private RSA_3072 key with help of openssl library (which must be available in your PATH)

npm run license

Checks if all depenedent libraries are in a set of allowed libraries. Used by jenkins CI/CD pipeline.

npm run license:summary

Prints out a license summary for the whole dependency tree.

npm run pkg

Creates the binary files with the CLI for Windows, Linux and MacOS.

The content of the community tools and libraries documentation pages is licensed under the MIT License.
Siemens API Notice applies.
Back to top