Introduction

Installation

Install Node.JS and install globally via NPM:

$ npm install -g zeysdk

To test the installation, open a terminal and type:

$ zeysdk --version

This will return the current version of the SDK.

Usage

Overview:

zeysdk add <ASSET_CLASS>/<FILENAME> --name=<NAME>
zeysdk compare [<FILENAME1> <FILENAME2> ...]
zeysdk create <APP_IDENTIFIER> --name=<NAME>
zeysdk delete <APP_IDENTIFIER>
zeysdk help
zeysdk link <INSTANCE_ID>
zeysdk pull [<ASSET_CLASS>/<FILENAME> ...]
zeysdk push [<ASSET_CLASS>/<FILENAME> ...]
zeysdk remove <ASSET_CLASS>/<FILENAME>
zeysdk rename <ASSET_CLASS>/<OLD_FILENAME> <ASSET_CLASS>/<NEW_FILENAME>
zeysdk run <ASSET_CLASS>/<FILENAME>
zeysdk sync [<ASSET_CLASS>/<FILENAME> ...]
zeysdk unlink <INSTANCE_ID>
zeysdk update <ASSET_CLASS>/<FILENAME>
zeysdk use <INSTANCE_ID>
zeysdk version
zeysdk whoami

Creating a new application

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

Instance login

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.

Also, for every linked instance, the SDK will create an app settings file such as settings/settings.<instanceid>.json.

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

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 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

Conflict Management

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.

Debugging

Usage

zeysdk run <ASSET_CLASS>/<FILENAME>

Description

Runs a given iXML 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.

Config files

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

The zeysdk.package.json contains metadata and other relevant information on the application itself
The zeysdk.assets.json contains metadata about the individual assets of the application
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 GmbH & Co. KG",
    "email": "info@zeyos.com",
    "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

YOU SHOULD NEVER MODIFY THIS FILE MANUALLY!!!

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

YOU SHOULD NEVER MODIFY THIS FILE MANUALLY!!!

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:

The connection settings, including token, URL, etc.
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.