pman: paramate Configurator Manager

What is pman?

The paramate Configurator Manager (or "pman") is a tool for syncing the code between a developer’s machine and the paramate server.

Since the files which are used by a configurator on the paramate cloud are hosted by the paramate servers, they need to be updated for new changes to be effective in the configurator. Without pman, the method to update the files of a configurator is to manually login to the paramate Admin page and use its interface to do that.

pman automates this process, making it faster and easier for a developer to manage such files, enabling them to do it via the command line from their local machines. It helps to accelerate the development of configurators and makes developing, testing and publishing easier.

pman can sync both, the code files for the CAD part and the renderer files. You can choose if you want to upload to or download from the paramate could to keep the local and cloud files in sync. If you are familiar with git, this is similar to git's push and pull commands.

How to install and use pman?

It can be directly used as an executable. Simply download the binary file for your operational system from this list:

You can call the executable directly from command line locally. How to make it globally accessible from anywhere in your machine is system specific - look for "how to add an executable to path" for instructions on how to do it.

Before pman can start syncing, a config file has to be generated for pman in the folder where you start the tool from. It stores the settings to your project and tells pman which local folder to sync with which configurator on the paramate cloud. The config file can either be generated manually or by using the command pman configure. When generating manually please note that the config file has to be called .pmanrc.

As an example, the necessary content of such a file can look like this: 

{ 
  userName: 'myuser',
  password: 'mypassword',
  configuratorId: 'fabccdfc-9e79-4f1a-be6e-d5da6fc0e196',
  configuratorFolder: './configurator',
  rendererFolder: './renderer'
}

The configuratorFolder (more precisely the folder for the configurator’s CAD files) and rendererFolder are the relative paths from the place where you start the tool to your configurator and renderer files, respectively.

More settings are possible in the config file and will be published soon.

If installed globally pman can be called from any folder and it is most convenient to do it from the local folder where you develop your configurator. Otherwise, either a copy of the binary is needed in that folder or the path to that folder needs to be taken into account in the config file.

The main commands are:

pman status: it compares the files of the configurator in paramate to the local files

pman push: it pushes the files of the configurator to paramate

pman pull: it pulls the files of the configurator from paramate

pman test: it will try to start your configurator in the paramate cloud, and tells you whether or not it worked. It also shows error messages for your code.

pman push test: When test is combined with the push command, it performs the test after the pushing is done. It is recommended using this when you did changes that could cause an error.

You can learn more about the usage of the tool by running pman help.

Workflow using pman

After installing pman you still need some means of seeing the output configurator generated with our CAD code and the effect of changes. If you are not developing you own frontend (yet), you can just use the test configurator frontend accessible from the paramate admin for that. If you are not yet familiar with the paramate admin we recommend to read the Getting Started tutorial before using pman. There you will learn as well about starting the built-in test configurator frontend using the "play"-button.

Note, that if using trCAD for the CAD part, it may be a good idea to use the VS Code extension provided for trCAD for developing from your local machine.

A typical simple workflow looks like that:

  1. Set up a configurator on the paramate cloud. (Do the Getting Started tutorial to learn how.)
  2. Configure pman to sync with that paramate configurator using command pman configure.
  3. Open your (test) configurator frontend in a browser.
  4. Open a console for executing pman.
  5. Apply changes to your CAD code.
  6. Push your code changes to the paramate cloud and retrieve debug output using command pman push test.
  7. Refresh your frontend.

Repeat steps 5 – 7 as needed for each coding iteration.

For recommendations regarding the workflow in a more advanced setting with different versions for development and deploy and for working collaboratively on a configurator, contact us for advice.