zeysdk/README.md

SDK for ZeyOS

ZeyOS SDK CLI
=============

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

Installation
------------

Install [Node.JS](https://nodejs.org) 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](docs/entities.md); 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](docs/views.md)
* `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](https://www.ixmldev.com) or [Zymba](https://www.zymba.info) 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

```json
{
  "identifier": "mydemoapp",
  "signature": "fhe734e9feznc94zm9",
  "name": "Demo Application",
  "description": "A sample ZeyOS application",
  "author": {
    "name": "ZeyOS, Inc.",
    "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

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

```json
{
  "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

```json
{
  "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](https://github.com/zeyosinc/zeysdk/blob/master/LICENSE)