# com.innovaphone.manager (AP Manager API)

This API is used to add APs (App Platforms) to a PBX. When the AP is added, it allows to find the App Instances provided by the AP and to configure the PBX to use these App Instances.
In addition to that, a plugin for the AP Manager (app installer) is available where new apps can be installed, updated or uninstalled.
The API consists of the following functional blocks.

AP Domain Management
  A mechanism to add a new AP to a PBX. For this a random password is set for the domain of the PBX inside the Manager, so that a AP object using this password can be installed on the PBX. For this an AppWebsocket connection with a default (dummy) password is established. A new domain can be created and authenticated with the AP Manager password.
AP Instance Management
  The AP object in the PBX provides an API as hidden App for other Apps within the client. This API is used to announce all the App Instances available for the domain and provides functions to configure domain passwords on a given App Instance.
AP Manager Plugin - app installer
  The app installer plugin provieds a view of the AP Manager appstore and allows to install, update or uninstall apps. New instances are implicity created (or removed) with the corresponding domain. After the app is installed, the instance can be configured on the PBX through its respective plugin.

## AP Domain Management

An AppWebsocket connnection with a default password "-" is used for this interface.

### Login

Normal AppWebsocket Login is used.

url
  ws(s)://<AP host address>/manager/manager-domain
password
  "-"
domain
  The PBX domain

### RegisterDomain

        {
        "mt": "RegisterDomain",
        "pwd": string
        "managerPwd": string
        }

With this message a new domain is registered on the AP. For security reasons, the AP Manager password must be provided so that the domian is added.
The domain is the domain used for the login.

pwd
  Password to be set
managerPwd
  AP Manager password

### RegisterDomainResult

    {
        "mt": "RegisterDomainResult"
    }

Message sent by the AP as response to RegisterDomain

## AP Instance Management

Instance management is done through myApps API com.innovaphone.manager. This API is provided by a hidden App provided to the PBX when the Websocket Connection to http(s)://<AP host address>/manager/manager-domain-api is opened from the AP object in the PBX.

### ManagerControls

    {
        "mt": "ManagerControls"
    }

The ManagerControls message is used to read the list of PBX Manager plugins available on the given domain

### ManagerControlsResult

    {
        "mt": "ManagerControlsResult",
        "protocol": string,
        "ap": string,
        "apDn": string,
        "host": string,
        "controls": [<Control>,...]
    }

With this message the list of available PBX Manager plugins is returned

protocol
  http: or https:
ap
  SIP URI user part of the AP object
apDn
  Display name of the AP object
host
  Host address of the AP
controls
  Array of objects of type Control

### Objects

Control

    {
        "api": [string,...]
        "uri": string,
        "png": string,
        "lang": string
    }

Description of an PBX Manager plugin control

uri
  The relative URI of the plugin (.js)
png
  The relatiive URI of the plugin icon (.png)
lang
  The relative URI of a language file, with the reserved property "pluginTitle" for the title of the plugin.

### SetInstancePassword

    {
        "mt": "SetInstancePassword",
        "path": string,
        "pwd": string
    }

Used to set the password of an instance. On success, the instance is edited with the new password and an AppWebsocket connection can then be established.

path
  The webserver path used to identify the instance
pwd
  The new password of the instance

### SetInstancePasswordResult

    {
        "mt": "SetInstancePasswordResult",
        "error": string
    }

Returns the result for SetInstancePassword

error
  If present the operation was not successful

### GetInstanceLogin

    {
        "mt": "GetInstanceLogin",
        "path": string,
        "app": string,
        "challenge": string,
    }

Used to get a login for a given instance. This maybe used in the fgetlogin callback of the AppWebsocket connection. With this it is possible to authenticate at instances without an App Object present in the PBX, just by having access to the App Platform Manager.

path
  The webserver path as configured for the instance. This is used to identify the instance for which a login is requested.
app
  An App object name used for the login. Usually this has no meaning.
challenge
  The challenge received from the instance to which a login is requested. This is received as argument of the fgetlogin callback of the AppWebsocket library.

### GetInstanceLoginResult

    {
        "mt": "GetInstanceLoginResult",
        "app": string,
        "sip": string,
        "domain": string,
        "guid": string,
        "dn": string,
        "digest": string
    }

The login, which can be used for the App Instance. This object can directly passed to the login function of the AppWebsocket library.

## AP Manager Plugin - app installer

The app installer plugin facilitates the management of apps and the configuration of the instances on the PBX.

### GetManagerInfo

    {
        "mt": "GetManagerInfo"
    }

The GetManagerInfo message is used to retrieve information about the App Platform and AP Manager

### GetManagerInfoResult

    {
        "mt": "GetManagerInfoResult",
        "platform": string,
        "platformLabel": string,
        "build": string,
        "version": string,
        "label": string,
    }

### AcceptUserAgreement

    {
        "mt": "AcceptUserAgreement",
        "accept": boolean,
        "user": string
    }

The AcceptUserAgreement message is needed to accept the AP Manager appstore user agreement and get access to the appstore.

accept
  to indicated that the user is agreement is accepted or not.
user
  The logged in PBX user;

### AcceptUserAgreementResult

    {
        "mt": "AcceptUserAgreementResult",
        "accepted": boolean
    }

### CheckUserAgreement

    {
        "mt": "CheckUserAgreement"
    }

The CheckUserAgreement message checks if the user agreement of the AP Manager appstore is accepted or not.

### CheckUserAgreementResult

    {
        "mt": "CheckUserAgreementResult",
        "accepted": boolean
    }

### RequestAppStore

    {
        "mt": "RequestAppStore"
    }

The RequestAppStore message requests all the apps available on the configured app store in the AP Manager

### AppStoreServiceAdded

        {
        "mt": "AppStoreServiceAdded",
        "id": string,
        "folder": string,
        "title": string,
        "manufacturer": string,
        "infourl": string,
        "logo": string,
        "versions": [],
        "state": {},
        "support": string,
        "requirement": string,
        "licenseInfo": string,
        "licenseType": string,
        "eula": string,
        "langs": [],
        "categories": [],
        "apps": []
    }

### AppStoreResult

    {
        "mt": "AppStoreResult"
    }

### InstallService

     {
        "mt": "InstallService",
        "appServiceID": string,
        "title": string,
        "folder": string,
        "binary": string,
        "manufacturer": string,
        "copy": [],
        "version": {
            "build": string,
            "label": string,
            "id": string,
            "compatibilty": string
        },
        "userAgreementAccepted": boolean,
        "domain": string
    }

The InstallService message is used to install a new service on the AP. On success, a new instance with the same domain is implicitly added and started.
The instance can be configured on the PBX through its corresponding PBX Manager plugin.

### ServiceInstalled

    {
        "mt": "ServiceInstalled",
        "filename": string,
        "appServiceID": string,
        "title": string,
        "initilaStatus": boolean,
        "currentStatus": boolean,
        "manufacturere": string,
        "startTime": ulong64,
        "versions": []
     }

### InstallServiceResult

    {
        "mt": "InstallServiceResult",
        "error": string
    }

Indicates whether an app service was successfully installed or not.

### UpdateService

     {
        "mt": "InstallService",
        "appServiceID": string,
        "title": string,
        "folder": string,
        "binary": string,
        "manufacturer": string,
        "copy": [],
        "version": {
            "build": string,
            "label": string,
            "id": string,
            "compatibilty": string
        },
        "domain": string
    }

The UpdateService message is used to update a service to any avialable version. The update would not be possible (through this plugin) if a service have multiple instances with different domains.
Updating the AP Manager and the Webserver app is also not possible.

### ServiceUpdated

    {
        "mt": "ServiceInstalled",
        "filename": string,
        "appServiceID": string,
        "title": string,
        "initilaStatus": boolean,
        "currentStatus": boolean,
        "manufacturere": string,
        "startTime": ulong64,
        "versions": []
     }

### UpdateServiceResult

    {
        "mt": "UpdateServiceResult",
        "error": string
    }

Indicates whether an app service was successfully updated or not.

### RemoveService

     {
        "mt": "InstallService",
        "appServiceID": string,
        "domain": string
    }

The RemoveService message is used to uninstall a service.
The uninstall would only remove the corresponding instance with the specified domain. If no other instances are present, then the whole service is uninstalled.

### ServiceRemoved

    {
        "mt": "ServiceInstalled",
        "filename": string,
        "appServiceID": string
     }

### RemoveServiceResult

    {
        "mt": "RemoveServiceResult",
        "error": string
    }

Indicates whether an app service was successfully uninstalled or not.