Publishing a node server

Publishing a node server means making it available to be installed by PG3 or PG3x. There are 3 node server stores and as a developer, you can publish your node server into any (or all) of these stores. Once a node server has been published to a node server store, and has been marked as available, it will show up in the PG3(x) Node Server Store page in PG3(x).

The different node server stores are available to separate node servers in various states of development.

Local: Each instance of PG3(x) has a local node server store. This is a store that maintained only in the PG3(x) database and is not accessible to any other instance of PG3(x). Publish to this store while developing and testing your node server.
Non-Production: Or Beta is a node server store for node servers that are not ready for production. If you want/need wider testing of your node server, and expect to be making changes frequently, publishing to the non-production store makes the node server available to everyone. However, it is important to set user expectations such that they realize node servers in the non-production store may be less stable, have bugs, and change frequently.
Production: For all generally available node servers. Once published here, users will expect a working, stable node server.

Node server's are identified by a unique node server id (or nsid). You can publish the same node server, with the same nsid to multiple stores. When the nsid is the same, user's can install/re-install from any store that has a node server with that nsid. Specifically, if you first publish to the non-production store and a user installs the non-production version. Then you copy the node server/nsid to the production store, the user can then re-install from the production store without having to get a new license.

However, if you publish to the production store with a new nsid, users who installed from the non-production store will be required to get a new license to install from the production store.

Keeping track of what nsid is being used in each store submission is very important. If you can the nsid of your store entry when updating, you force the users to get new licenses for your node server. They won't be happy if they have to purchase new license because you mistakenly changed the nsid.

The PG3 node server developer tools menu allows you list all of your published node servers, submit new node servers to be published, and edit information about your published node servers. When you log into PG3 and connect with your portal account, PG3 will add a Developer menu item.

From the menu, select "Add new node server" and you will be presented with a form that allows you to enter all of the information about the node server you wish to publish. The form will provide some guidance on required fields and field formatting. Once you have entered all of the information, scroll to the bottom of the form. Make sure you have selected the correct store and click the "Submit to NS Store" button. You should then get a dialog box letting you know your submission was successful. If the submission wasn't successful, the most likely reason is because you are missing some required piece of information.

Node server submission field definitions

Name [required]

The name of the node server. This will be displayed everywhere so should be meaningful. Limited to 14 characters and no spaces

Author [required]

The person who authored the node server. This is displayed in the store listings. May be an email address.

Language [required]

What language is the node server written in. Used to determine how to run the node server. For example, a node server written in Python needs to use the Python interpreter to run the node server. Valid choices are Python (3.x), Node.js, or binary.

Executable Name [required]

The file name that PG3(x) will execute when starting the node server.

Documentation [required]

This is a URL that points to additional documentation on the node server. For example you may want to point this at a user's manual for the node server. The URL must be generally accessible. The node server store will create a button that redirects to this URL.

Link to License [required]

This is a URL that points to the EULA for your node server. Should be generally accessible. The node server store will create a button that redirects to this URL.

Short Poll (seconds) [required]

This is the default short poll interval. PG3(x) will send a poll command to your node server at this interval. Valid entries are 1 - MAXINT.

Long Poll (seconds) [required]

This is the default long poll interval. PG3(x) will send a poll command to your node server at this interval. Valid entries are 1 - MAXINT. This also must be greater than the short poll interval

Version [deprecated]

Multiple versions can now be supported, use the version field in the purchase options to identify the node server version.

Profile Version [required]

The version of your node server's profile files. TODO: determine if this is ever used.

Install Script [required]

The name of the script that will be run during node server installation. For Python based node servers you'll want to run pip to installed required Python libraries. For Node.js based node server you'll want to run npm to install required node modules.

Persistent Folder [optional]

A folder name that your node server creates in the node server home directory after the node server is installed. This folder can hold persistent configuration info that will survive a re-install process.

Status [required]

Status can be one of three states:

New - added to store, but not displayed in store listings
Active - displayed in store listings, available to install
Inactive - not displayed in store listings, but not available for existing users to re-install

see below for more details on the status values

Initial Log level [required]

Sets the level of logging after the node server is installed. Users can change this at any time.

Critical - only messages marked as critical will be logged
Error - messages marked error or critical will be logged
Warning - messages marked warning, error or critical will be logged
Info - messages marked info, warning, error, or critical will be logged
Debug - messages marked debug, info, warning, error, or critical will be logged

NS Info Poll [optional]

How often PG3 will send node server info to your node server. This is only used for a very specific type of node server, probably not yours.

Enable Discovery [optional]

When checked adds a "Discover" button to the PG3(x) node server details page in the UI. When the user clicks the "Discover" button an event will be sent to your node server. Used for user initiated device discovery operations.

Enable OAuth2 [optional]

When checked your node server can route OAuth2 handshaking through PG3(x). See OAuth HowTo for more details.

Works on Polisy [optional]

When checked adds text to the node server information text saying that this node server works on Polisy controllers (checked by default)

Works on eisy [optional]

When checked adds text to the node server information text saying that this node server works on eisy controllers (checked by default)

Description [required]

A text description of your node server. This is displayed as part of the store listing so should be fairly brief.

Custom Parameters [optional]

You can enter a JSON string here that defines the default key/value pairs that make up the custom parameters your node server uses for configuration. For example

{{'{'}}"username":"","password":""{{'}'}}

will create two custom parameters, one for username and one for a password. Both will be blank by default.

Device Configuration [optional]

A description of how to set up devd type hardware device info. PG3x will use this to enable specific hardware devices for use by your node server. For example a USB IR receiver.

Oauth Configuration [optional]

See OAuth HowTo for more details.

Node Server Custom Data [optional]

Text data that is sent to your node server at install time. For example, if you have a secret key that is needed for API communication but you don't want to embed the key in the source code, you can specify the key here. When you node server starts, it can subscribe to the NSCustom event and PG3(x) will send this data over that event to your node server. This is pushed out periodically so it can be updated by the developer at any time.

ReadMe Text [optional]

This is where you put the full description of your node server and can include any specific info the user may need to use your node server. Basically your node server documentation.

Change Log [optional]

Can be a list of changes or a list of changes by version for your node server. It's way to notify users what has changed in each new version.

Select Store to submit to [required]

Which node server store; Production, Non-Production, or Local to save this to. Note that you can edit an entry in one store and then save it to another. However, keep in mind the nsid discussed earlier. Don't edit an existing node server and try to use that as a template for a new node server. Your new node server will have the same nsid as the original which is probably not what you want. Use the Add New Node Server to add a new node server to the, edit and switch stores to copy an existing node server to a different store.

Add Purchase Option [minimum of one purchase option required]

Clicking this opens a new form where you enter the details for a specific version/option of your node server. See below for more details.

Version [required] - Version number
Edition [required] - Free, Standard, Professional
Option Type [required] - Purchase type; Perpetual, Subscription, Trial, Upgrade, Edition Upgrade
Cost [required] - Maybe zero for a free node server. Must be a number.
Installation URL [required] - Where will PG3(x) find the node server to install it
Branch [optional] - If the install URL is a git repository, what branch do you want it to use
Choose File [optional] - If your node server is packaged as a .zip or .tgz file, you can upload that package to UDI's secure S3 node server storage area and the Installation URL will be updated to point there.

Submit to NS Store

Click this when you have everything filled out and are ready to send it to a store.

More details on node server status

The "Status" field can be set to "New", "Active", "Inactive". New submits the info to the store database but does not make it available to users. Active means the node server is available and Will show up in PG3's node server store listing. Inactive will remove the node server from PG3's node server store listing, but not remove it from the database. If Inactive is set, no one will be able to make new purchases of the node server but existing purchases will still function.

More details on purchase options

Your node server must contain at least one purchase option or no one will be able to install the node server. Use the "Add Purchase Option" button to open a dialog box and create a purchase option. You can have 3 basic types of purchases:

Trial - Allow free access for a specific period. Once the trial period is over, the node server will stop running
Perpetual - A one-time purchase that allows the purchaser to install and use the node server for as long as it is available.
Subscription - A time limited purchase. If the subscription is not renewed with-in the subscription period, the node server will stop running until it is renewed

Trial purchases are time limited and have no cost associated with them.
Perpetual purchases can be set to any price including zero ($0) if you don't want to charge for the node server.

Additional sub-types of purchases are also available but not yet fully functional. The PG3 store will support multiple tiers or editions of a node node server. Currently there are three edition types:

Free - A free edition. This should be free to install and use.
Standard - A step up from the free edition. More features should be enabled.
Professional - More features and capabilities should be available.

Customers should be able to upgrade from one edition to a higher edition for the difference in cost between the two.

You can also create purchase options to charge for upgrades. An upgrade purchase option allows you to charge an additional fee to upgrade from one version to another. The system uses the version number to determine what will be upgraded. I.E. if the customer has purchased version 1.0.0 and you make a version 2.0.0 available as an upgrade. Any version between 1.0.0 and less than 2.0.0 would be considered a free update. Any 1.x.x version could then be upgraded to 2.0.0 at the upgrade cost.

If you wish to no longer maintain a node server you have a couple of options. You can mark the node server as Inactive in the store and no new installation of it will be allowed. Or you can remove it from the store. Once removed from the store, existing purchases will become invalid and existing users will no longer be able to use the node server. Before taking this action, it is recommended that you contact other developers or UDI and try to transfer support of your node server to minimize the impact on users.