ZeyOS SDK CLI

Current Version is 0.9.0 - ZeySDK is still in beta! Use at your own risk

Installation

Install Node.JS and install globally via NPM:

npm install -g zeysdk

Usage

App Management

Usage

• zeysdk create <APP_IDENTIFIER> --name=<NAME>

Description

Creates a new ZeyOS application manifest and creates the application's directory structure:

/<APP_IDENTIFIER>
 |- /resources
 |- /services
 |- /settings
 |  |- defaultsettings.json
 |  |- settingscode.ixml
 |  |- usersettingscode.ixml
 |- /weblets
 |- .zeysdk.assets.json
 |- .zeysdk.package.json
 |- .zeysdk.sync.json

Asset Management

Usage

• zeysdk add <ASSET_CLASS>/<FILENAME> : Add an asset, e.g. zeysdk add services/test.ixml
• zeysdk update <ASSET_CLASS>/<FILENAME> : Update the asset properites
• zeysdk remove <ASSET_CLASS>/<FILENAME> : Remove an assets (will be deleted after sync)
• zeysdk rename <ASSET_CLASS>/<OLD_FILENAME> <ASSET_CLASS>/<NEW_FILENAME> : Renames a resource

There are three types of asset classes:

• services
• resources
• weblets

zeysdk add weblets/picklist.ixml --name="Picking List" --type=detached --view=billing.details_transaction

Options

For Services

• name: The service name (mandatory)
• type: The service type; Options:
  • NULL: No built-in event (default)
  • timing: Service is called periodically (requires properties schedule and interval)
  • remotecall: Service is called via remote HTTP request
  • after_creation: Triggered after an object is created (requires property entity)
  • before_modification: Triggered before an object is modified (requires property entity)
  • after_modification: Triggered after an object is modified (requires property entity)
  • after_creation_modification: Triggered after an object is created or modified (requires property entity)
  • before_deletion: Triggered before an object is deleted (requires property entity)
  • after_deletion: Triggered after an object is deleted (requires property entity)
• schedule: The daily starting point as minute of the day (e.g. 16:30 = 16.5 * 60 = 990); only applicable for type timing, defaults to 0:00
• interval: The interval by minute in which the service should be called (e.g. 10 means every ten minutes); only applicable and mandatory for type timing, must be greator than zero
• entity: The ZeyOS entity class. For options, see List of ZeyOS Entities; only applicable for types after_creation, before_modification, after_modification, after_creation_modification, before_deletion and after_deletion
• accesskey: The security access key; optional and only applicable for type remotecall
• url: The service URL - can be used when working with external hooks and scripts

For Resources

• name: The resource name (mandatory)
• mimetype: The resource MIME type (mandatory)

For Weblets

• name: The weblet name (mandatory)
• type: The weblet type (mandatory); Options:
  • integrated: Weblet will be visible below the ZeyOS menu bar
  • standalone: Weblet is standalone and not embedded within the ZeyOS UI
  • detached: Weblet is standalone and will be opened in a new tab/window
  • popup_framed: Weblet will be display in a popup including title bar. (requires properties width and height)
  • popup_plain: Weblet will be display in a plain popup without title bar. (requires properties width and height)
  • embedded_framed: Weblet will be displayed within an open panel
  • embedded_collapsed: Weblet will be displayed within a closed panel
  • embedded_plain: Weblet will be display within a plain iframe without enclosing panel
• view: The ZeyOS view that the weblet applies to. For options, see List of ZeyOS Views
• width: The frame width
• height: The frame height
• url: The weblet URL - can be used when working with external hooks and scripts

Examples

Add a new service:

zeysdk add services/sendreminder.ixml --name="Send reminders" --type=timing --schedule=360 --interval=60

Update the service properties:

zeysdk update services/notifycontact.zy --type=after_creation --entity=contacts

Note: When a service type changes, obsolete properties will be removed from zeysdk.assets.json, e.g. in this case entity would be removed.

Rename a service:

zeysdk rename services/sendreminder.ixml services/notifycontact.zy

Synchronization

Usage

• zeysdk link <INSTANCE_ID> --url=<URL> : Create/update a platform link
• zeysdk unlink <INSTANCE_ID> : Remove a platform link
• zeysdk use <INSTANCE_ID> : Switch between platform links
• zeysdk whoami : Show information about the active platform link

Options

• --url: The ZeyOS URL; if no URL is supplied, the default URL is https://cloud.zeyos.com/<INSTANCE_ID>/
• --user: The ZeyOS user name or e-mail (case-insensitive)
• --password: The user's password

Description

When you work on your application, you will require a ZeyOS platform for testing and development. For this purpose, you will need to link your application to a ZeyOS instance. Since you might want to deploy your application on multiple instances, you can also quickly switch between instances via zeysdk use.

Every time you create a new instance, a instance specific configuration file is created as .zeysdk.sync.<instanceid>.json. The currently active instance configuration is always simply stored as .zeysdk.sync.json.

Debugging

Usage

• zeysdk run <ASSET_CLASS>/<FILENAME>

Description

Runs a given iXML or Zymba script in the platform's console. This means that the code is not executed locally on your machine, but runs on your linked ZeyOS instance.

Synchronization

Usage

• zeysdk compare [<ASSET_CLASS>/<FILENAME> ...]
• zeysdk sync [<ASSET_CLASS>/<FILENAME> ...]
• zeysdk push [<ASSET_CLASS>/<FILENAME> ...]
• zeysdk pull [<ASSET_CLASS>/<FILENAME> ...]

Options

• compare: Only compares local assets with remote assets on the server side; no changes will be made
• sync: Newer assets will replace older assets, both locally and on the server side
• push: Push local changes to the server; remote state will be overwritten
• pull: Pull remote changes from the server; local state will be overwritten

Description

If a conflict arises, the SDK will offer you to create a set of files with the suffix .mine and .theirs so that you can use an external merge application to differentiate and resolve the conflict.

Config files

When using the SDK, you will notice that a couple of configuration files are being created:

1. The zeysdk.package.json contains metadata and other relevant information on the application itself
2. The zeysdk.assets.json contains metadata about the individual assets of the application
3. The zeysdk.sync.json contains asset synchronization states in regards to the linked ZeyOS instance

We highly recommend using the SDK's interface to change those files and refrain from editing them directly.

However, in some cases you might want to automate certain tasks through additional scripts and task runners - in such cases it is certainly useful to have a better understanding about the underlying file structure and properties.

BE CAREFUL WHEN MANIPULATING THE SYNC STATES, YOU ARE PUTTING YOUR SYSTEM INTEGRITY AT RISK!

The Application Manifest File: zeysdk.package.json

The zeysdk.package.json describes the application's properties

{
  "identifier": "mydemoapp",
  "signature": "fhe734e9feznc94zm9",
  "name": "Demo Application",
  "description": "A sample ZeyOS application",
  "author": {
    "name": "ZeyOS, Inc.",
    "email": "[email protected]",
    "id": "zeyos",
    "homepage": "https://www.zeyos.com"
  },
  "repository": "https://github.com/zeyosinc/sdkdemo.git"
}

The manifest file consists of the following sections:

Application identifier

The identifier property also defines the applications namespace.

Application signature

The signature is for all apps that are approved and sigend by ZeyOS.

Name and description

Simply put a short descriptive name (< 64 characters) and description (< 512 characters) in here.

Author information

Your company name, e-mail, author ID (if registered with ZeyOS), homepage

Repository

Link to the Git repository

The Application Assets File: zeysdk.assets.json

The zeysdk.assets.json represents the properties of all included assets, for example

{
  "services": {
    "api": {
      "mimetype": "text/x-zymba",
      "type": "remotecall",
      "accesskey": "orhf984ht48"
    },
    "check_contact": {
      "mimetype": "application/ixml+xml",
      "type": "after_modification_creation",
      "entity": "contacts"
    }
  },
  "resources": {
    "test": {
      "mimetype": "application/ixml+xml"
    },
    "template": {
      "mimetype": "text/html"
    }
  },
  "weblets": {
    "chart": {
      "mimetype": "application/ixml+xml",
      "type": "popup_framed",
      "width": 500,
      "height": 400
    }
  }
}

The ZeyOS Sync File: zeysdk.sync.json

The zeysdk.sync.json file is created whenever you are syncing an application with a ZeyOS instance.

The instance configuration stores the authentication information when executing zeysdk link <INSTANCE_ID>. By using zeysdk use <INSTANCE_ID> a user can switch between different instances.

Example

{
  "id": "sdkdemo",
  "url": "https://cloud.zeyos.com/sdkdemo/",
  "user": 2,
  "application": null,
  "token": "ee0b44835f52cfe8a53c46f963f9badb2cc8eaa9",
  "identifier": "ZeySDK",
  "expdate": null,
  "syncstates": {
    "settings": {
      "hash": "9p843rsdufh983f98ef",
      "lastmodified": 4389574398534435
    },
    "defaultsettings": {
      "hash": "9p843rsdufh983f98ef",
      "lastmodified": 4389574398534435
    },
    "services": {
      "api": {
        "hash": "9p843rsdufh983e78sf",
        "lastmodified": 4389574398534435
      }
    },
    "resources": {
      "test": {
        "hash": "9p843rsdufh983f98ef",
        "lastmodified": 4389574398534435
      },
      "template": {
        "hash": "9p843rsdufh983e78sf",
        "lastmodified": 4389574398534435
      }
    },
    "weblets": {}
  }
}

As you can see in the example, the file consists of two core sections:

1. The connection settings, including token, URL, etc.
2. The sync states for settings, services, resources and weblets

The connection consisting of the platform URL and the authentication token. Those settings are being updated, whenever you run zeysdk link in your application directory.

The sync states for settings, resources, services and weblets consist of the file name and the sync state on the server. The lastmodified property is the timestamp of the last modification date. The hash value is the hash of the file contents.

If the lastmodified and hash properties are empty, it means that the sync state is unknown, e.g. when an new file has been created. In our example, the service api has no sync state on the server.

This could lead to the following situations when syncing:

• The file does not exist on the server - in this case it will be created
• The file exists on the server - this would lead to a conflict
  • The file can be replaced on the client (Resolution method: theirs)
  • The file can be replaced on the server (Resolution method: mine)

If the lastmodified and hash properties exist, it will be compared with the server's current state. This could lead to the following situations when syncing:

• The file does not exist on the server - this would lead to a conflict
  • The file can be removed on the client (Resolution method: theirs)
  • The file can be created on the server (Resolution method: mine)
• The file exists on the server and lastmodified/hash does not equal the last known sync state - this would lead to a conflict
  • The file can be replaced on the client (Resolution method: theirs)
  • The file can be replaced on the server (Resolution method: mine)
• The file exists on the server and lastmodified/hash equals the last known sync state - in this case, the file will be copied to the server.

License and Copyright

• Copyright 2017-2018 by ZeyOS, Inc. - all rights reserved
• Source code is licensed under BSD 3-Clause