{"id":31450678,"url":"https://github.com/mindsphere/mindsphere-node-sdk-examples","last_synced_at":"2025-10-01T04:27:11.101Z","repository":{"id":48788066,"uuid":"329870638","full_name":"mindsphere/mindsphere-node-sdk-examples","owner":"mindsphere","description":null,"archived":false,"fork":false,"pushed_at":"2022-09-22T11:40:27.000Z","size":1981,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-03-02T08:26:40.210Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mindsphere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-15T09:46:02.000Z","updated_at":"2022-06-03T05:13:44.000Z","dependencies_parsed_at":"2023-01-19T04:03:13.274Z","dependency_job_id":null,"html_url":"https://github.com/mindsphere/mindsphere-node-sdk-examples","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/mindsphere/mindsphere-node-sdk-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindsphere%2Fmindsphere-node-sdk-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindsphere%2Fmindsphere-node-sdk-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindsphere%2Fmindsphere-node-sdk-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindsphere%2Fmindsphere-node-sdk-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mindsphere","download_url":"https://codeload.github.com/mindsphere/mindsphere-node-sdk-examples/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindsphere%2Fmindsphere-node-sdk-examples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277795777,"owners_count":25878649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-01T02:00:09.286Z","response_time":88,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-01T04:27:08.308Z","updated_at":"2025-10-01T04:27:11.095Z","avatar_url":"https://github.com/mindsphere.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MindSphere SDK for NodeJS # \nAPI clients and References.md\n\n## Full documentation\n\nThe full documentation can be found at [https://developer.mindsphere.io/resources/mindsphere-sdk-node/jsdoc/index.html](https://developer.mindsphere.io/resources/mindsphere-sdk-node/jsdoc/index.html)\n\n## 1 - Preparation\n### Prerequisites to use the MindSphere SDK for Node.js ###\n- 1. NodeJS version 8.0 or higher installed where application will be running.\n- 2. User authorization token or app credentials with required scopes for Mindsphere Service APIs.\n    \n    - 2.1 Environment variables set up in local machine to run application in local. \n    - 2.2 When application hosting type is `SELF_HOSTED`, the variables must be configured on server.\n    - 2.3 When hosting an application in Cloud Foundry, the variable must be present as application's environment variables. This is achieved by adding variables in the manifest file.\n\n  \n\n\n#### Environment Variables ####\n\nApplication Credentials\n| Sr. No. | Environment Variable | Description |\n|-----|--------------|--------------|\n|1 | MDSP_OS_VM_APP_VERSION| Store App Version in environment variable named `MDSP_OS_VM_APP_VERSION`. | \n|2 | MDSP_OS_VM_APP_NAME| Store App Name in environment variable named `MDSP_OS_VM_APP_VERSION`. | \n|3 | MDSP_KEY_STORE_CLIENT_ID| Store App Client ID in environment variable named `MDSP_KEY_STORE_CLIENT_ID`. |\n|4 | MDSP_KEY_STORE_CLIENT_SECRET| Store App Client Secret in environment variable named `MDSP_KEY_STORE_CLIENT_SECRET`. |\n|5 | MDSP_HOST_TENANT | Store the name of the tenant on which application is hosted in environment variable named `MDSP_HOST_TENANT`. |\n|6 | MDSP_USER_TENANT | Store the name of the tenant from which application is being accessed in environment variable named `MDSP_USER_TENANT`. |\n|7 | HOST_ENVIRONMENT | Store the region in environment variable named `HOST_ENVIRONMENT`. If not specified, HOST_ENVIRONMENT defaults to `eu1` in region Europe 1 SDK and to `cn1` in region China 1 SDK.\n\n\n- App Credentials will suffice to use SDKs.\n- For more information about credentials please visit [Token Handling](https://developer.mindsphere.io/resources/mindsphere-sdk-java-v2/token_handling_v2.html)\n###### Note \n\u003e App Credentials and Application Credentials refers to same concept. These terms might be used interchangeably in the document.\n\n##### env:\n  HOST_ENVIRONMENT: eu1\nIf not specified, HOST_ENVIRONMENT defaults to eu1 in region Europe 1 SDK and to cn1 in region China 1 SDK.\n\n## 2 - Download \n##### Downloading the MindSphere SDK for Node.js\nDownload the MindSphere SDK for Node.js from the [Siemens Industry Online Support (SIOS) Portal](https://support.industry.siemens.com/cs/document/109757603/mindsphere-sdk-for-java-and-node-js?dti=0\u0026lc=en-US).\n\n\n\n## 3 - Host Node Sample Project on MindSphere\nMindSphere provides two ways to host an application - `Cloud Foundry Hosted` and `Self Hosted`.\nFor `Cloud Foundry Hosted` see 3A - 1 and for `Self Hosted` see 3A-2.\n\n### 3A - 1 : Upload app to CloudFoundry and fetch app URL\n\nThe following steps describe way to deploy Node Sample Project on Cloud Foundry.\nIf you want to host your own application then skip to step 3(Push the App to CloudFoundry).\n\n#### 1. Clone this repository.\n####\n```\ngit clone https://github.com/mindsphere/mindsphere-node-sdk-examples.git\n```\n#### 2. Install required dependencies.\n\n- Download Node JS SDK from  [Download](#2---download).\n- Unzip the downloaded file.\n- Navigate to \u003csome path where unzipped folder is located\u003e/mindsphere-node-sdk_1.0.0/modules/\n- Copy .tgz files of required dependent service/services in 'packages' folder. (For this project(mindsphere-sdk-node-examples) we will need all the .tgz files but you can choose to use only required subset of all avaiable SDKs for your project.)\n- Kindly note that Tenant Credential Support is removed from Node SDKs from now. Hence we strongly recommend using\n  latest version(1.0.5) of mindsphere-core library.\n- For convenience `packages` folder is already created in root directory of project.\n- For convenience, package.json is populated with relative path to copied dependencies.\n\n#### 3. Push the App to CloudFoundry.\n- Navigate to directory where cloned project directory is present. In this case navigate to sample-nodejs-app.\n- In order to push app to CF, user must login to cloudfoundry. To login user can opt for either of two ways.\n    - Jump to [Login to CF](#login-to-cf)\n- At this point you are successfully logged in CF.\n- Prepare manifest.yml file for pushing. File content pertinent to sample project are as :\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/manifest.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n- For convienience, sample manifest.yml is added in root directory of project.\n- `path` specifies where to look for application. Here in this case, our app is located inside `mindsphere-node-sdk-examples` folder.\n- Environment variables are listed under `env`. Since sample application demonstrates use of MindSphere SDKs, environemnt variables  are only specific for Token Generation. In case of other application, user can append the list with his/her own environment variables.\n- As mentioned in 1 - Prerequisites, either of Tenant Credentials/ Application Credentials would suffice for getting token.\n- In sample file variables for both type of credentials are mentioned but user can choose to use only one.\n- If opting for App Credentials, user will not have values of all environment variables at this point. In this scenario either put some dummy values or do not add variables at all. CF provides command to set environment variables hence they can be set later on.\n- Now run the command `cf push`.\n- Once application is successfully deployed check for app status using command `cf app routi`.\n- Note down app URL displayed on screen.\n\u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/cfappurl.png\" width=\"400\"\u003e\n\u003c/p\u003e\n\n### 3A - 2 : Deploy the application as Self Hosted Application.\n- Self Hosted Applications are deployed by user on desired server.\n- User must note down URL where application is hosted.\n\n### Step 3A - 3 : Create Application in Developer Cockpit.\n\n#### Save the Application\n1. Open the **Developer Cockpit** from the Launchpad and select the **Dashboard tab**.\n2. Click on **Create new application**.\n3. Select Type Standard and Infrastructure MindSphere Cloud Foundry if you have deployed application in cloud foundry. In case of self-hosted application select Self Hosted.\n4. Enter an arbitrary Display Name and an Internal Name which will be part of the application URL. The Internal Name cannot be changed after initial creation!\n5. Enter a version number.\n    - MindSphere supports a Major.Minor.Patch scheme.\n    - Versions must start with a major number \u003e= 1.\n    - The version cannot be changed after saving.\n6. Upload an icon for your application.(Optional step)\n7. Enter the component name. The component name must be the same as specified in the __*manifest.yml*__ file.\n    - In case of sample project `mindsphere-node-sdk-examples` component name will be **routi** and component url can be obtained by \n      running `cf app routi` on command line.\n    - In case of Self Hosted Application, component name and URL will be as per customer's deployment strategy.\n8. Add one endpoint for your component using /** to match all of your application paths.\n9. Set the content-security-policy according to the examples:\n    - For Europe1 :     default-src 'self' *.eu1.mindsphere.io; style-src * 'unsafe-inline'; script-src 'self' 'unsafe-inline' *.eu1.mindsphere.io code.jquery.com cdnjs.cloudflare.com; font-src 'self' 'unsafe-inline' fonts.gstatic.com *.eu1.mindsphere.io; img-src * data:;\n    - For Europe2:    default-src 'self' *.eu2.mindsphere.io; style-src * 'unsafe-inline';  script-src 'self' 'unsafe-inline'  *.eu2.mindsphere.io code.jquery.com cdnjs.cloudflare.com;  font-src 'self' 'unsafe-inline' fonts.gstatic.com *.eu2.mindsphere.io;  img-src * data:;\n10.  Click on **Save**.\n\n#### Add roles and Scopes\n1. Switch to the Authorization Management tab.\n2. Select the application you just created.\n3. Create an application scope, e.g. \u003cprovided-application-name\u003e.subtenant.\n4. Add the following Core roles to enable access to the respective APIs. For this project - `mindsphere-node-sdk-examples`, you will need following API roles. If required roles are not added then endpoints specific to those services will not work as expected.\n\u003cp\u003e\n\u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/apiroles.PNG\" width=\"400\"\u003e\n\u003c/p\u003e\n\n#### Register the Application\n1. Switch to the Dashboard tab.\n2. Open the application details.\n3. Click on Register.\n\n#### Generate App Credentials\n1. Switch to the Authorization Management tab.\n2. Click on **App Credentials** tab.\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/ac.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n3. Click on **Issue access** button.\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/issueaccessac.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n4. Select **Read And Write** .\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/readandwrite.PNG\" width=\"400\"\u003e\n    \u003c/p\u003e\n5. Click on **Submit** button.\n6. You will be presented with client ID and client secret for application.\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/cidcsecret.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n7. Store these values at secure location as they are displayed only once.\n\n#### Set environment variables\n1. In case of App Credentials, at this point you have all the required values for corresponding environment variables - \n`MDSP_OS_VM_APP_NAME`, `MDSP_OS_VM_APP_VERSION`, `MDSP_KEY_STORE_CLIENT_ID`,`MDSP_KEY_STORE_CLIENT_SECRET`,`MDSP_HOST_TENANT`, `MDSP_USER_TENANT`.\n\n| Sr. No. | Environment Variable | Value |\n|-----|--------------|--------------|\n|1 | MDSP_OS_VM_APP_VERSION| Version you provided while creating application. | \n|2 | MDSP_OS_VM_APP_NAME| Internal name of your application(Can be seen in Application Details in Developer Cockpit). | \n|3 | MDSP_KEY_STORE_CLIENT_ID|  App Client ID displayed on screen in last step. |\n|4 | MDSP_KEY_STORE_CLIENT_SECRET| App Client Secret displayed on screen in last step. |\n|5 | MDSP_HOST_TENANT | Name of the tenant you are currently working upon. |\n|6 | MDSP_USER_TENANT | This specifies the name of tenant which will use the application. Since we are currently in developing and testing phase, `MDSP_USER_TENANT` == `MDSP_HOST_TENANT`. |\n\n2. Set the values of this environment variables in Cloud Foundry.\n```\ncf set-env routi \u003cVARIABLE-NAME\u003e \u003cVARIABLE-VALUE\u003e\n```\nIf you have provided any other value for application name then modify the command accordingly.\nAs suggested by Cloud Foundry documentation, restage the app.\n````\ncf restage \u003cAPP-NAME\u003e\n````\n3. In case of Self Hosted application, you need to store these values as per deployment strategy. Also make sure this values can be accessed in application.\n      \n#### Assign the App and Access via Launchpad\n1. Navigate to MindSphere Launchpad -\u003e Settings -\u003e Users\n2. Select a Developer you want to assign this application to. (You can assign it to yourself as well)\n3. Scroll down a bit and click on **Edit direct assignments**.\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/assignapp.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n4. In the **Application Roles** section, search your application by internal name.\n5. Select checkboxes for both admin and user.\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/addadminuser.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n6. Click on **Next**.\n7. Click on **Save**.\n\nNow concerned developer should be able to access the application via launchpad.\n\n#### Access the application.\n1. Navigate to MindSphere Launchpad.\n2. Click on your application tile.\n3. You should see something like :\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/sp95changes/images/Homescreen1.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n4. By clicking on any endpoint showing on above image you should see like :\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-python-sdk-examples/blob/swaggerui-changes/images/putaspectcall.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n5. By clicking 'try it out' button you can make api call by putting correct parameters and requestbody. then you will get response like :\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-python-sdk-examples/blob/swaggerui-changes/images/respnseapi.png\" width=\"400\"\u003e\n    \u003c/p\u003e    \n\n6. Domain url is **Application URL** displayed on Application details page.\n    \u003cp\u003e\n    \u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/appurl.png\" width=\"400\"\u003e\n    \u003c/p\u003e\n\n#### Create an asset via application.\n1. For creating an asset we will first create aspect type. From created aspect type we create Asset type. Next we finally create an asset based on created Asset type.\n2. First hit the endpoint PUT /assets/putaspect/{id}/{ifmatch}.\n3.  If call is succesful, note down aspect id and aspect name from the response.\n4. Next, hit PUT /assets/putaassettype /{id}/{ifmatch}. Pass noted aspect id and aspect name value in payload for creating asset type. \n5. If call is succesful, note down id from the response.\n6. Next hit GET /assets/root to get root asset of the tenant. Note down id of an asset from the response.\n7. Finally we will now create an asset. Pass id from step 5 and parent id from step 6 in the payload for creating an asset.\n8. If asset creation is successful, you should see created asset in the call GET /assets/assets.\n9. All the created resources (aspect type, asset type and asset) are visible on Asset Manager application on MindSphere Launchpad.\n\n###### Note \n\u003e Sample payload for endpoint is provided whenever required. For more information about payload, please refer `sample-payload/\u003cservice-name\u003e/sampleinput` file.\n\u003e For now, swagger endpoints are provided for **asset management, timeseries and event analytics** service only. For other services, endpoints can be tried via entering url in browser.\n\n###### Note \n\u003e We require XSRF token for calling PUT, POST/PATCH, DELETE APIs (For GET endpoints, XSRF_TOKEN is not compulsory). The value of XSRF token can be passed in request header. This token is available in cookies by name `XSRF-TOKEN`. We have fetched this token from cache in the application and put it in request header.  \n\n\n\n\n### 3B - Set up Node Sample Project For Local Machine\n\nThe following steps describe the way to set up a sample project to test on local machine.\nThis is to facilitate any bug resolution on local developer setup.\nPlease follow prerequisite section for environment variables, how to get them and how to store them.\n\n##### 1. Clone this repository.\n####\n```\ngit clone https://github.com/mindsphere/mindsphere-node-sdk-examples.git\n```\n##### 2. Install required dependencies.\n\n- Download Node JS SDK from  [Download](#2---download)\n- Unzip the downloaded file.\n- Navigate to \u003csome path where unzipped folder is located\u003e/mindsphere-node-sdk_1.0.0/modules/\n- Copy .tgz files of required dependent service/services in 'packages' folder. (For this project(mindsphere-sdk-node-examples) we will need all the .tgz files but you can choose to use only required subset of all avaiable SDKs for your project.)\n- For convenience, package.json is populated with relative path to copied dependencies.\n- For convenience `packages` folder is already created in root directory of project.\n- Navigate inside the root directory of project if you are not in there.\n```\ncd mindsphere-node-sdk-examples\n```\n- Run below command to install required dependecies mentioned in package.json file.\n```\nnpm install\n```\n###### Note \n\u003e If you face errors while `npm install` mentioning particular '\u003cfile-name\u003e.tgz file not found' then kindly verify dependency file name in packages folder and that mentioned in package.json file. This could be also due to incorrect relative path mentioned in package.json file. If so then modify path in package.json wherever required.\n\n##### 3. Run the app.\n####\n```\nnpm start\n```\n##### 4. Access the app.\n1. Navigate to 'http://localhost:3000' (You can use any browswer of your choice).\n2. Domain URL in this case will be 'localhost:3000'.\n\u003cp\u003e\n\u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/sp95changes/images/homescreen.png\" width=\"400\"\u003e\n\u003c/p\u003e\n\n###### Note \n\u003e Sample payload for endpoint is provided whenever required. For more information about payload, please refer `sample-payload/\u003cservice-name\u003e/sampleinput` file.\n\u003e For now, swagger endpoints are provided for **asset management, timeseries and event analytics** service only. For other services, endpoints can be tried via entering url in browser.\n\n\n### Login to CF\n- To login to cloudfoundry user can opt for either of two ways.\n#### Using -sso\n- `cf login -a [cloudfoundry_login_url] -sso`\n- This command will prompt for Email and Password.\n- Enter webkey credentials that you use for tenant login.\n- You will be logged in as long as credentials in previous step are correct.\n##### OR\n#### Using Service Credentials on MindSphere.\n- Navigate to MindSphere Launchpad -\u003e Settings -\u003e Service Credentials.\n\u003cp\u003e\n\u003cimg src=\"https://github.com/mindsphere/mindsphere-node-sdk-examples/blob/master/images/sc.png\" width=\"400\"\u003e\n\u003c/p\u003e\n\n- Create service credentials by providing details asked on page.\n- Generated service credentials(combination of username and password) are displayed on screen. Store them in secure location as they displayed only once.\n- Use command `cf login -a [cloudfoundry_login_url] -u \u003cusername\u003e -p \u003cpassword\u003e`\n\n###### Note \n\u003e Service Credentials application is accessible to Tenant Admins only. If you are not a Tenant Admin then contact your Tenant Admin to generate these Service Credentials for you.\n\n## 4 - Prepare the app to hand it over to Operator Cockpit\nPlease refer [Handing over app to Operator Cockpit](https://developer.mindsphere.io/howto/howto-develop-and-register-an-application.html#handover-the-application-to-the-operator-tenant)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindsphere%2Fmindsphere-node-sdk-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmindsphere%2Fmindsphere-node-sdk-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindsphere%2Fmindsphere-node-sdk-examples/lists"}