Skip to content

Instantly share code, notes, and snippets.

@dapepe

dapepe/zeysdk-readme.md

Last active December 8, 2017 09:23
Show Gist options
  • Save dapepe/ab63c0032a95667f7ba759758cf164ec to your computer and use it in GitHub Desktop.
Save dapepe/ab63c0032a95667f7ba759758cf164ec to your computer and use it in GitHub Desktop.
Download ZIP
ZeySDK README
Raw
zeysdk-readme.md

ZeyOS SDK CLI

First: GET /sync Then create the PATCH document

Installation

Install Node.JS and install globally via NPM:

npm install -g zeysdk

Usage

App Management

Usage

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

Description

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

/<appidentifier>
 |- /resources
 |- /services
 |- /settings
 |  |- defaultsettings.json
 |  |- settings.json
 |- /weblets
 |- zeysdk.package.json
 |- zeysdk.assets.json
 |- zeysdk.sync.json

Asset Management

Usage

  • zeysdk add <ASSET_CLASS> <FILENAME> : Add an asset, e.g. zeysdk add service 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> <NEW_FILENAME> : Renames a resource

There are three types of asset classes:

  • resource
  • service
  • weblet

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

Options

For services
  • name: The service name (mandatory)
  • type: The service type (mandatory); Options:
    • timing: Service is called periodically (requires properties schedule and interval)
    • remotecall: Service is called via HTTP
    • after_creation: Triggered after an object is created (requires property entity)
    • before_modification: Triggered before an object is modified (requires property entity)
    • after_modifivation: 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 and mandatory for type timing
  • interval: The interval my minute in which the service should be called (e.g. 10 means every ten minutes); only applicable and mandatory for type timing
  • entity: The ZeyOS entity class. For options, see List of ZeyOS Entities; only applicable and mandatory for types after_creation, before_modification, after_modifivation and after_creation_modification.
  • accesskey: The services security access key; optional; only applicable for type remotecall (optional)
  • url: The service url - can be used when working with external hooks and scripts.
For weblets
  • name: The weblet name
  • type: The weblet type (mandatory). Options:
    • integrated: Weblet will be visible blow 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. (required properties width and height)
    • popup_plain: Weblet will be display in a plain popup without title bar. (required 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 encloding panel
  • view: The ZeyOS view that should be expanded (mandatory). For options, see List of ZeyOS Views
  • width: The popup width
  • height: The popup height
  • url: The service url - can be used when working with external hooks and scripts.
For Resources
  • name: The resource name (mandatory)

Examples

Add a new service:

zeysdk add service sendreminder.ixml --name="Send reminders" --type=timing --schedule=600 --interval=60

Update the service properties:

zeysdk update service sendreminder.ixml --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 schedule and interval would be removed.

Rename a service:

zeysdk rename service sendreminder.ixml notifycontact.zy

Synchronization

Usage

  • zeysdk link <INSTANCE_ID> : Create/update a platform link
  • zeysdk unlink <INSTANCE_ID> : Remove a platform link
  • zeysdk use <INSTANCE_ID> : Switch between linked instances
  • 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
  • --password: The user's password

Description

When you work on your application, you will require a ZeyOS platform as testing and development environment. For this purpose, you will need to link your application with a ZeyOS instance. Since you might want to deploy your application on multiple instances, you can also specify an instance ID in order to switch between instances via zeysdk use.

Every time you create a new instance, a new instance configuration is created in zeysdk.sync.<instanceid>.json. The currently active instance configuration is stored in 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 ZeyOS development machine.

Synchronization

Usage

  • zeysdk compare [<FILENAME1> <FILENAME2> ...]
  • zeysdk sync [<FILENAME1> <FILENAME2> ...]
  • zeysdk push [<FILENAME1> <FILENAME2> ...]
  • zeysdk pull [<FILENAME1> <FILENAME2> ...]

Options

  • compare: Only compares the client side with the server side. No changes will be transferred
  • sync: New files will replace old files on both sides - local and remote.
  • push: Push local changes to the server - server changes will be overwritten
  • pull: Pull changes from the server - local changes 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 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, containing all relevant information about your app
  2. The zeysdk.assets.json, referencing the individual files in your app
  3. The zeysdk.sync.json which stores file sync states with your ZeyOS platforms

We highly recommend using the SDK's interface to edit those file and restrain 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 Asset File: zeysdk.assets.json

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

{
  "resources": {
    "test": {
      "mimetype": "application/ixml+xml"
    },
    "template": {
      "mimetype": "text/html"
    }
  },
  "services": {
    "api": {
      "mimetype": "text/x-zymba",
      "type": "remotecall",
      "accesskey": "orhf984ht48"
    },
    "check_contact": {
      "mimetype": "application/ixml+xml",
      "type": "after_modification_creation",
      "entity": "contacts"
    }
  },
  "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 <instanceid>. By using zeysdk use <instanceid> 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
    },
    "resources": {
      "test": {
        "hash": "9p843rsdufh983f98ef",
        "lastmodified": 4389574398534435
      },
      "template": {
        "hash": "9p843rsdufh983e78sf",
        "lastmodified": 4389574398534435
      }
    },
    "services": {
      "api": {
        "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, resources, services 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 called 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment