Intro

A command line utility that makes it easier to work with the Thingworx VSCode Project Template. Its purpose is to make it easer to update the project template by moving most files not directly related to the thingworx project itself into external dependencies. This way, whenever any improvements or bug fixes are made, developers will only need to update the dependencies and not do any changes to their actual project.

It includes the tasks that were previously defined in that project's gulpfile and will contain any future utilities.

Usage

This is primarily meant to be used with a project based on the Thingworx VSCode Project Template. It can also be used with an empty project to initialize a thingworx project in it.

To use it, run npm install --save-dev bm-thing-cli then run any of the available commands with npx twc <command>. Running the tool with no command will print out a message listing the available commands. Alternatively, you may install this globally via npm install -g bm-thing-cli which will allow you to use it outside of thingworx projects (for example to run the init command) and without the npx prefix.

The available commands are detailed below:

Repository Layout

There are two kinds of projects that bm-thing-cli understands:

• TypeScript projects — source lives in src/, is compiled to a ThingWorx extension package, and deployed via upload / push / deploy.
• XML projects — folders that store raw ThingWorx entity XML, pulled from and pushed to a server directly via source control (no compilation step).

Single TypeScript project

A basic repository has a single twconfig.json at the root:

MyProject/
├── package.json
├── twconfig.json       // { "projectName": "MyProject" }
└── src/                // TypeScript source files

Multi-project repository

When multiple projects share a repository, each lives in its own subfolder under src/. TypeScript and XML projects can coexist:

MyRepo/
├── package.json
├── twconfig.json               // { "projects": [...] }
└── src/
    ├── MyTsProject/            // TypeScript project
    │   ├── twconfig.json
    │   └── src/
    └── MyXmlProject/           // XML project
        ├── twconfig.json
        ├── src/                // entity XML files
        └── data/               // optional: entity data files

XML project twconfig.json

An XML project folder's twconfig.json supports two optional arrays in addition to the standard fields:

• projects — maps the folder to one or more ThingWorx project names. All listed projects are exported/imported together. If omitted, the folder name is used as the sole project name.
• data — declares entity data files (DataTables, Streams, etc.) that are committed to source control alongside entity definitions. These travel with the project and represent its required configuration/initial state. Each entry specifies an entityType, entityName, and a file path relative to the project folder.
• runtimeData — declares entity data files that are gitignored and represent environment-specific runtime or migration data. These are managed via the separate pull-runtime-data / push-runtime-data commands.

{
    "projects": ["MyProject.PRJ", "MyOtherProject.PRJ"],
    "data": [
        {
            "entityType": "DataTables",
            "entityName": "MyConfig.DT",
            "file": "data/MyConfig.DT.twx"
        }
    ],
    "runtimeData": [
        {
            "entityType": "DataTables",
            "entityName": "MyRuntimeData.DT",
            "file": "runtimeData/MyRuntimeData.DT.twx"
        }
    ]
}

Data files are written to (and read from) the path specified in file when running pull --data and push --data respectively. Runtime data files are managed via pull-runtime-data and push-runtime-data.

declarations

Usage:

npx twc declarations

Builds the thingworx declarations for the project, making it possible to reference thingworx entities via their collections, e.g. Things.MyThing.

watch

Usage:

npx twc watch

Builds the thingworx declarations for the project, making it possible to reference thingworx entities via their collections, e.g. Things.MyThing, whenever there are any changes in the src folder.

build

Usage:

npx twc build [--merged|--separate] [--debug] [--trace] [--projects]

Builds a thingworx extension package from the typescript project which can be installed on a thingworx server. Arguments:

• --merged: Can be used with a multi-project repository. Causes the projects to be bundled in a single extension.
• --separate: Can be used with a multi-project repository and is the default if --merged isn't specified. Causes the projects to each have their own separate extension.
• --debug: Creates a debug build.
• --trace: Creates a trace build.
• --projects: If specified, this limits the projects that are built to the ones specified in this argument. Usage:

twc build --projects=Project1,Project2

upload

Usage:

npx twc upload [--merged|--separate] [--debug] [--trace] [--remove] [--retain-version] [--extensions] [--data] [--projects]

Builds a thingworx extension package from the typescript project, then imports it on the server defined in either the environment or package.json. Arguments:

• --remove: If specified, the current version of the extension(s) will be removed prior to installing the new version.
• --retain-version: If specified, the version of the extension(s) in the package.json is not incremented. Useful if the version is driven out of external tools.
• --extensions: If specified, any .zip files in the local extensions folder will also be uploaded.
• --data: If specified, any data files declared in the project's twconfig.json (data array) will be uploaded to the server via the DataImporter endpoint.

deploy

Usage:

npx twc deploy [--merged|--separate] [--debug] [--trace] [--remove] [--retain-version] [--extensions] [--data] [--projects]

Builds a thingworx extension package from the typescript project, then imports it on the server defined in either the environment or package.json. After the installation is complete, it runs the services marked with the @deploy decorator.

push

Usage:

npx twc push [--merged|--separate] [--debug] [--trace] [--remove] [--retain-version] [--extensions] [--data] [--projects]

Builds a thingworx extension package from the typescript project, then imports it on the server defined in either the environment or package.json, while uploading any XML projects as regular editable entities. Arguments:

• --extensions: If specified, any .zip files in the local extensions folder will also be uploaded.
• --data: If specified, any data files declared in the project's twconfig.json (data array) will be uploaded to the server via the DataImporter endpoint.

XML project folders support a projects array in their twconfig.json to map a single local folder to multiple ThingWorx project names. All listed projects are uploaded together. See 2.3.0 changelog for details.

pull

Usage:

npx twc pull --xml [--data] [--projects]

Pulls XML entities from the thingworx server for all local XML projects. If the --projects argument is specified, any projects included must also exist locally. Arguments:

• --xml: Required. Pulls entity XML from the server using source control export.
• --data: If specified, any data files declared in the project's twconfig.json (data array) will be downloaded from the server via the DataExporter endpoint and written to their configured local paths.

pull-runtime-data

Usage:

npx twc pull-runtime-data [--projects]

Exports runtime data files from ThingWorx for all local XML projects. Reads the runtimeData array from each project's twconfig.json. These files are gitignored and represent environment-specific data for migrations.

push-runtime-data

Usage:

npx twc push-runtime-data [--projects]

Imports runtime data files into ThingWorx for all local XML projects. Reads the runtimeData array from each project's twconfig.json.

See XML project twconfig.json above for how to configure multi-project folders and data file tracking.

remove

Usage:

npx twc remove [--merged|--separate]

Removes the current version of the extension(s) from the thingworx server defined in either the environment or package.json.

add-project

Usage

npx twc add-project

Adds a new thingworx project to the repository. If the repository is currently a single project, it will convert it into a multi-project repository.

init

Usage

twc init

Creates a new thingworx project in the current folder. This will automatically create files such as package.json and tsconfig.json, but without the sample files included in the Thingworx VSCode Project repository. Unless you already have a package.json file with bm-thing-cli defined as a dependency in the current folder, this command requires that this cli utility be installed globally.

upgrade

Usage

npx twc upgrade

Upgrades a thingworx project from the old gulp-based build script to using this utility, by removing the gulpfile and uninstalling its associated dependencies, and then installing bm-thing-cli.

Development

Pre-Requisites

The following software is required:

• NodeJS: needs to be installed and added to the PATH. You should use the LTS version.

The following software is recommended:

• Visual Studio Code: An integrated developer enviroment with great javascript and typescript support. You can also use any IDE of your liking, it just that most of the testing was done using VSCode.

Development Environment

In order to develop this extension you need to do the following:

1. Clone this repository
2. Run npm install. This will install the development dependencies for the project.
3. Start working on the project.

File Structure

ThingCLI
│   readme.md         // this file
│   package.json      // node package details
│   license           // license file
└───scripts           // build scripts
│   │   clean.js            // script that cleans the dist folder
└───src               // main folder where your developement will take place
│   │   file1.ts            // typescript file
|   |   ...
└───dist              // files used in the distribution

Build

To build the project, run npm run build in the root of the project. This will generate the appropriate files in the dist folder.

Contributors

• BogdanMihaiciuc: main developer
• stefan-lacatus: pull and push commands, retainVersion argument, method helpers, generate-api command, bug fixes, multi-project xml folders
• CozminM: compatiblity with thingworx 8.5

License

MIT License