Welcome to the appivo documentation-site. This is the place to find details regarding the concepts involved when using and/or building applications based on the Appivo platform. If you can’t find an answer to what you are looking for please visit our community forum.

The perhaps quickest way to get acquainted with the appivo-platform is to checkout our video-tutorials. They are linked to from relevant places like the builder itself – check the help-link in top right corner of the screen. Here’s also an index of them all. It’s highly recommended to watch a couple to get started and then use them as a reference as needed.

Beginner Tutorials

1. Introducing the Appivo-platform. This video shows the building-blocks of an application but doesn’t go into any details.
2. Building a simple app using the AppWizard. This video shows how to build a very simple application using the AppWizard.
3. Creating a simple sensor-application This video shows how to build a very simple internet-of-things sensor-application.

Signing up with Appivo is easy! Just visit the signup page, enter the requested information (your first- and last name, your country, a valid email-adress, and your organization’s name), and click the “Sign Up” button. An activation email will be sent to the email adress you specified.

The activation email contains a link that takes you to the password selection page. Once you have specified your desired password, your account is activated and you will be taken to the login page where you can login

If you cannot find the activation email:

• Check your spam folder, occasionally the email ends up there.
• Sometimes it can take a minute or two for the mail to arrive, wait a bit and see if it arrives.
• Send out another activation email by following the Resetting your Password guide.

You can also signup using your Facebook or LinkedIn account. On the signup page, click either the “Connect with Facebook” or “Connect with LinkedIn” button, fill in the missing details and click sign up. Signing up using Facebook/LinkedIn allows you to login using your Facebook/LinkedIn account.

Log in by specifying your email adress and password. If you have forgotten your password, see Resetting your Password.

If you signed up with Facebook/LinkedIn you can click the “Login with Facebook” or “Login with LinkedIn” buttons to login.

To reset your password, go to the login page and click “Forgot password”. You will be asked to specify your email adress, after which an activation email will be sent. Clicking the link in the activation email will take you to a password selection page, letting you change your password.

If you cannot find the activation email:

• Check your spam folder, occasionally the email ends up there.
• Sometimes it can take a minute or two for the mail to arrive, wait a bit and see if it arrives.
• Try sending out another activation email.

When logging in to the Appivo platform you will be taken to the “My Apps” screen. This screen displays all the apps you have subscribed to and lets you launch the apps by clicking their icons. At first your “My Apps” screen is probably empty, this is because you have not subscribed to any apps yet.

Before you can use an app you must subscribe to it. Use the navigation bar at the top of the page to open the marketplace. To subscribe to an app on the marketplace, click on the app, then click on the subscribe button.

Many apps allow their subscribers to configure the app for themselves. To configure an app, open the app in the marketplace and click the “Configuration” tab.

You can also use the marketplace to assign users to your app. Users assigned to the app will be able to see and launch the app from their “My Apps” screen.

Also notice that if your application has IoT deviceprofiles you will need to assign the profiles to devices. This is done under the device-assignment tab where you can enable/disable deviceprofiles and specify what tags a device must have to receive the profile.

After subscribing to an app you should assign users to it. You can assign the users through the marketplace, or use the account page to do it. The “Account Page” is found in the user menu (top right). In the “Account Page”, select the “Users” tab to find the list of all your users. Clicking a user in the list allows you to edit the user’s details, including the apps the user is subscribed to.

When editing a user’s details, you can also add roles to the user. Roles control what a user is allowed to do with the platform and with the apps they are subscribed to. By assigning roles you can designate which users are administrators and which are standard users, for example.

Subscribed apps are started from the “My Apps” page. Just click the icon of the app you wish to start. Some apps are also available on the Google Play Store / Apple App Store.

An app is a composed of several parts: Models and records hold the data that your app wants to keep track of. Rules are triggered by certain events in the app and perform arbitrary actions that are defined by you (the developer). Queries can be used to fine-tune access to the models and records, adding powerful filtering and merging capabilities. User interfaces and views are the graphical interfaces that users normally interact with. They contain widgets such as buttons, datagrids, labels and textfields. Similar to rules, widgets can also react to events (like a button click) and perform actions. By using all these features together, you can create powerful and intuitive apps with endless possibilities!

The Wizard is a short step-by-step guide that allows you to quickly and easily create the foundation for your app. It is the recommended starting point for anyone new to Appivo. Important note: Don’t worry too much about making errors in the Wizard. It is always possible to correct them later on!

A video showing the wizard in action is available here.

This step allows you to define the models of your app. Models describe the data that your app uses. Example models include:

• Customers
• Articles
• Orders
• Images
• Schedules

For simplicity there exists several templates that define models for common use cases. For more specific use cases you can create the models yourself. It is also possible to import models. For example, importing the user model from System allows you to bind app-specific data like schedules to users (binding models together is done in the next step, relations).

Models consist of attributes. Each attribute describes some important property (for instance, a customer’s address or phone number or an articles price) and has a data type that defines how the attribute looks and behaves.

For more information on models, see models

After defining your models, the next step is to define how they can relate to each other.

For example, it makes sense that customers place orders. This indicates that we should have a relationship between the customer model and the order model. It also makes sense that each order should contain of a number of articles, meaning we should probably also have a relationship between the order and article models.

Every relation has a cardinality that describes how the relation can be bound. For example, a customer can place several orders, but each order can only ever have one customer associated with it (the customer who placed the order). For more information about relations and cardinality, see relations.

Roles define what users are allowed to do within your app. For example, in a video sharing app, all users should be able to upload videos, but only specific users (the moderators) would be able to delete videos. This step allows you to define multiple roles and declare what each role is allowed to do with each model.

In this step you will provide some information that the wizard uses to generate user interfaces (UI’s) for your app. You can decide that you only want your app to be accessible from a mobile UI (intended for phones), or maybe that your app is accessible from a mobile UI but any data must be created using a desktop UI (intended for computers). Tick the boxes that you wish and the wizard will use this data, together with the models and relations that you specified earlier and generate views for your app. For more information, see user interfaces and views.

The most fundamental component in a system that manages information is a description of that information. What exactly is it that your application will manage ? Orders ? Vehicles ? Contacts ?

Telling the system what information we’re dealing with is typically the first step when building an application, all else depends more or less on that. A full description of the pieces of information and how they relate to each other is called an application data model.

An application data model is made up several distinct models where each individual model represents some part of the information you are managing. If you think about the solution that you want to create several nouns will probably come to mind, these nouns – perhaps customer, order, article, adress, invoice etc are likely to be models. A good starting point is to try to understand what different bits of information are involved in your application. It’s important to distinguish between something that is a model and something that is just an attribute of a model.

Example

Lets say that we want to create a simple ordering system – and the words that come to mind are order, article, invoice, customer, adress, city, email-adress, order-date, delivery-date. The first thing to do is to get a grip on how the information relates. For instance – it’s an ordering system so the concept of an order is likely central to the application, so is customer and invoice. Email-adress however is an attribute of a customer – a customer has an email-adress, it also has an adress and an adress consists of several pieces of data – city, state, zipcode, country. It can be a challenge for novices to distinguish between what constitutes a model and what is merely an attribute of a model. Typically something that can be described as “just” a number or piece of text, or a date is an attribute. If you think of the concept “order” it means much more than just a number or a piece of text, although it most definitely would have a special attribute called “number” to represents the order-number, that’s a strong indication that ‘order’ is a model. With the same reasoning – shipping-date is most likely not a model, but an attribute of the order-model.

On the appivo-platform the application data model is managed using the model-editor, it can visualize the data-model for you:

The model-editor can also show you a compact list of the models if you prefer. The visual editor is very easy to work with and gives you an immediate picture of how your data is structured. Adding new models is as easy as clicking a button, as is creating relations between models – but more on that later.

Double-clicking a data-model will open up an editor that lets you edit the attributes of that model.

Clicking close to the edge of a data-model and then keeping the mouse-button pressed while dragging the mouse will allow you to create a relationship between to models.

Right clicking on a model will bring up a context-menu with options to edit or delete the model. Deleting a model will automatically also delete all its relationships.

Models are the basis of almost any app. They describe the data that your app interacts with. Some examples of common models are: customers, receipts, orders, products.
In addition to describing data, models can also have relations between them. For example, an order is usually placed by a customer, which means that the orders and customers models should probably be related.

Creating a model is done by clicking the New Model button in the model view.

You will be prompted for a name and a type. The name is the model’s unique identifier. The type is one of the following:

• Data: The model describes some data, this is the standard model type.
  Examples: Customer, Receipt, Order, Product
• Document: The model describes a file. Use this if you want to store files.
  Examples: Photo, SoundRecording, Signature

After entering the name and type, press OK and your model will be created. Next, it’s time to add some attributes to the model. These attributes are needed for the model to be able to describe something. Adding attributes is done through the model editor, to open it, hold the mouse over your newly created model and click the blue cog that appears (or, from the model list, hold the mouse over the model and click the green pen that appears). Add attributes by dragging them from the right hand side of the screen into the model editor in the centre.

To add relations, go into the model editor, select the Relations tab (located close to the top of the screen) and click the Add Relation button.

A box will appear, letting you choose which model you wish to relate to. After picking a related model and pressing OK, the relation editor will pop up. The relation editor lets you set some necessary parameters that describe the relation between the two models.

• Relation Names: The names of the relation on the two models (for example, customer, order, car, owner). The name is only an identifier that is used when referring to the relation.
• Ownership: Indicates if one of the models is the owner of the other model. A related model cannot exist without it’s owner (for example, an order cannot exist without a customer).
• Relation Cardinality: Indicates how many records of a particular model the relation can refer to. (for example, a customer may place many orders, but an order can only have a single customer).

Rules and actions form a powerful way of making your application dynamic and provides you with a simple way of building logic. A rule is essentially a sort of trigger, there are several kinds of rules which are triggered under different circumstances. We will look each of them below. A rule can be associated with one or more actions, an action is something that happens when a rule triggers. Just like with rules there are several kinds of actions.

Example

In an ordering-system application we want to send an email to the customer when an order has been shipped. We can accomplish that by creating a rule that triggers when an order-record changes status from ‘PENDING’ to ‘SHIPPED’. The rule would be connected to a SendMail-action that will send an email to the customer.

Rules that trigger on data changes are used to react to users creating, editing or deleting records within the app.

Rules that trigger on a REST-request can be used to perform actions at will or to react to external input. This can be used to be able to triggered rules directly from a user interface which normally does not have access to server side data. A REST rule will be triggered any time  the platform receives a REST-request on the URL endpoint configured in the rule. For example a rule with the endpoint ‘myrule’ created in an app called MyApp would react to requests to the URL ‘http://apps.appivo.com/api/app/MyApp/service/myrule’. These rules can also be triggered by using a script in a user interface and calling context.invokeService with the name of the rule.

Rules that trigger on a schedule are simply rules that will be triggered based on a schedule. This can for example be used to continually send push notifications to users that have not interacted with the app and tell them that they need to do so.

An action is an instruction that will be executed in the platform when it is called upon. An Action can only be triggered by a rule but can be associated with several rules so that several different triggers can result in the same action being performed. When creating an action there are certain variables that are available to you when you are creating your titles and messages (See variables section).

When performing an action that will send some sort of message to users you have to specify to whom the message should be sent. This is done by using the addressing selection available on the action page. Selecting a role means that everybody with that role will be sent the message while selecting a user will send the message only specifically to that user. The record and previousRecord references are special in that they only apply under certain circumstances (more info in the variables section).

Both email and sms actions are simply used to send sms’s and emails to users. They both support using the variables in order to get context specific information in the message and title (no title for sms’s).

Push notifications are a great way to drive user interaction with your app and they support a lot of features. Push notifications can be used instead of sms’s and emails to send messages to users and are more direct than emails and cheaper than sms’s. The only limitation with push notifications is that they require you to create and distribute a hybridapp for your users. When defining a push notification you can decide what you
want to push to the user. The most basic push notification includes only a message and a title. The title is also optional and will be defaulted to the application’s name if left empty. The message and title work in the same way as for emails and sms’s and support using the same variables.

Buttons in the push message are a great way to let the user instantaneously interact with the app or to send a user to a specific screen of the app when clicked. Buttons are defined by the text displayed on them and a script that will be executed once the user presses the button. If the app is not running when the user presses the button, it will be launched for the user and the script will then execute.

The badge is the number that is displayed on top of the app icon on an iOS device and in the bottom right corner of a push message on Android. The badge is a great way to tell the user that there is information waiting for them in the app. The value to be sent to users as the badge is determined by a script defined as the badge function and its return value will be used as the badge number.

Scripts actions is how you add custom logic to your applications (see scripts section). This is where you can handle REST-requests that have triggered your rules and you can handle records and access control and many other things (see API documentation).

In the message and title fields and when addressing users, there are several variables accessible that relate to how the rule was triggered. The record reference is a reference to the record that was associated with triggering the rule. For example this could be the newly created record if the rule is setup to trigger on creation of a record. The previousRecord reference is only available with a rule that is set to react to after data changes and is only available for addressing an action. The previousRecord reference could for example be used to access the old phone number when a user updates the phone number set on a model. Rules triggered by REST will pass along the data sent in the rest body to the action and this will be accessible in the record reference. The user that was responsible for the rule triggering is also accessible through the ‘user’ variable. Further there are also variables that allow access to the host URL (‘hostURL’), the application config (‘app’) and locales (‘locale’).
All of these variables can be used in a template manner in the body and title. For example if you wish to include the first name and last name of the User that triggered the Rule in the title of a push you could write the following “{{user.firstname}} {{user.lastname}} triggered this!“. Similarly you might have a rule that reacts when a record of a certain model is updated and that model has a relation to the model user. In that case you could access that persons email by writing the following “Contact info email – {{record.User.name}}” (if the relation is called User).

Scripts are use to add custom logic to an app. This can for example be used to define what will happen when a user presses a button in a user interface or to perform a certain operation every time a record of a certain model is created. Adding scripts to your app is very easy and can be done without knowing anything about programming. At the same time, if you know programming, you are free to write advanced scripts to perform complex logic in your app without hindrance. The three different methods
for creating script can be seen as a hierarchy where QuickActions are the quickest and easiest way to perform the most common actions in an app. JavaScript is on the other end of the spectrum allowing you to create advanced actions with full control over what happens. Logic sits in the middle by still being easy to use but still allowing for full control over what the script does. This hierarchy is also visible by the fact that using a simple action also generates all the information needed for the more advanced script creation options. This allows one to use a QuickAction to perform a task and then switch over to using Logic or JavaScript and see how the same task could be performed using thoose methods. It is however not possible to create a script using JavaScript and then switch to Logic and see how it would look there.

QuickActions are a quick and easy way to perform the most common operation for the context of the script. All QuickActions are created by Appivo and guaranteed to work properly. To use QuickActions you simply open up a script editor in the builder (for example editing the callback for a button in a userinterface) and then select that the script should be defined using QuickActions (the script editor should default to this mode). Once the script editor is set to use QuickActions you simply pick the action
that you wish to perform from the dropdown and then input any parameters needed for the QuickAction.

Logic allows you to define app logic, more powerful than QuickActions, without writing any code. Resembling a puzzle, the pieces or blocks connect only in ways that make sense. The blocks are parsed and app code is generated.
The blocks are parsed from top to bottom, and have connections above and below that let you place them in the order you want them to be run. Some blocks also have connections to the right. Blocks connected on these right-side connections are called “arguments” and are used to configure or modify the behavior of a block. For example, a “Get user name” block may take a user block as an argument to specify which user’s name it should output. Figuring out which arguments fit in which block may be difficult. Luckily some help is available through tooltips. Just hold the mouse cursor over the colored part of a block and the tooltip will appear. The tooltip will usually have a short description, detailing the blocks purpose, along with information on the argument inputs and output value.

Blocks can be divided into a few notable types:

• Instruction blocks represent instructions – for example, a “send mail” block will send an email.
• Value blocks represent values such as numbers and text strings (like “hello”, for instance). Value blocks are often used as arguments to configure instruction blocks.

Note: Some blocks are both an instruction and a value. In these cases, the instruction normally comes down to finding the value that the block should represent. Arguments can be used to alter the value. For example, a “get name” block may have different values depending on which user is provided as the argument.

• Expression blocks perform logical and mathematical on their arguments, such as addition, substraction, or resolving whether a statement is true or not.
• Control flow blocks controls how your puzzle is parsed. These usually take an expression as the argument and directs the parsing on different paths depending on whether the expression is true or not. For example, you may want to display two different messages depending on if a user has a specific role or not, this could be performed with the “if” block.
• Variable blocks are special blocks that can be used to temporary store values. For example, maybe you want to overwrite the value of a widget, but need its old value for some calculations later in the puzzle, by storing the old value in a variable block this is possible.

Using JavaScript directly is the most advanced way to add custom logic to your app. It requires you to be familiar with programming and the syntax of JavaScript. Using JavaScript you have full access to all the APIs available in the platform and can create very advanced logic for your app. However if you are not used to writing code it is very easy to make misstakes that will cause the script to malfunction. Therefore it is recomended to use QuickActions and Logic for creating scripts until you feel
comfortable writing code.

By their nature client-side and server-side scripting are somewhat different. Client-side scripts run in the web-browser or on the mobile-device when the user interacts with your application. You can find API-documentation for client-side scripting over here.

Examples

1. Getting the value of a widget

var widget = context.getWidget("MyTextField");
var name = widget.getValue();

2. Setting the value of a widget

var widget = context.getWidget("MyTextField");
var name = widget.setValue("Bill Joy");

3. Submitting a form (including contents of child-forms);

var form = context.getForm("CustomerForm");
form.submit({
   full: true
});

4. Create a record from a form

Sometimes it is useful to create records from forms without submitting them. Providing the “full”-option will ensure that related records are included, if any, from child-forms and/or widgets holding related data (such as DataGrids etc).

var form = context.getForm("CustomerForm");
var record = form.createRecord({
   full: true
});

5. Opening another view for showing a record

Case: On the first view you have references to records, perhaps in a DataGrid, and when clicking on a representation of the record (perhaps a row in the DataGrid), you want to open another view with a form holding all the fields of the record.

context.setView("CustomerView", record.id);

6. Publishing a message to a topic

var bus = context.getMessageBus();
bus.publish("#MyTopic", {
   Name: "John Doe",
   Age: 37
});

7. Listen to messages sent out on a specific topic

var bus = context.getMessageBus();
bus.subscribe("#MyTopic", function(message) {
   context.log("Received a message " + message);
});

8. Updating an HTML-widget using a query

Case: Sometimes an HTML-widget is used to render data in a custom fashion. The HTML-widgets content is Handlebars-template, so it can reference data. In this example we have an HTML-widget, called MyHTML which needs data from a query as input.

// Get the widget
var html = context.getWidget("MyHTML");
// Get our query-handle
var qh = context.getQueryHandle("MyQuery");

// We just want the first record
qh.setLimit(1);

// Execute the query
qh.execute({
  onSuccess : function(result) {
     var res = result.getRecords();

     // We know we just request a single record
     var rec = res[0];

     // Refresh the html-widget with our record as input-data
     html.refresh(rec);
  }
});

In mobile user-interfaces you can make use of plugins for advanced functionality. Note that first of all you have to add the required plugins to your application. This is done from General -> Mobile Plugins. These plugins are standard Cordova plugins. Appivo has chosen to expose a selection of high quality plugins, if there is a plugin you feel should be included feel free to request it. Each plugin exposes its own API which you can make use of.

Example:

var scanner = context.getNativeAPI("BarcodeScanner");
scanner.scan(function(result) {
       alert("Scanned " + result.text);
   },
   function(error) {
       alert("Scanner failed " + error);
   }
);

Rules and Actions are executed on the server-side, this part of the documentation describes the Javascript API for programming ScriptActions.

The Context is the main interface when interacting with the system from Actions. Through it you can get access to system-features and general functionality. This section of the document provides a description of its API:

Examples

1. Creating a Record

// Create our Record-object
var record = context.createRecord("MyModel", {
  "Name": "James Gosling",
  "Age": 65
});

// Write it to the database
context.create(record);

2. Execute a Query and iterate over its Result

var result = context.query("MyQuery", {
  "MyParam": 7
});
try {
  while(result.hasNext()) {
    var record = result.next();
    context.log("Got record with ID: " + record.id);
  }
} finally {
  result.close();
}

3. Handle a ServiceRequest and interact with an external HTTP-service

// Get the ServiceRequest / ServiceResponse pair
var sreq = context.getRequest();
var sres = context.getResponse();

// Read the body of the ServiceRequest
var options = sreq.readObject();

// Get a value of the JSON-object from the ServiceRequest
var max = options.max;

// Issue an outbound request to a remote service
var response = context.sendHttpRequest({
   "method": "POST",
   "url": "https://foo.bar.com/service",
   "headers": {
      "content-type": "json",
   },
   "body": {
      "threshold": max
   }
});

// Check the response-status
if (!response.isFailed()) {
  // Read a JSON-object from the response
  var data = response.getContentAsObject();
  sres.setStatus(200);
  sres.write({
    "count": data.count
  });
} else {
  sres.sendError(500);
}

Roles are used to configure access to your application. Each role can be assigned permissions to use the models of you app. The permissions include Create, Read, Update and Delete operations. The role can then be given to users, giving them the permissions defined by the role.

User interfaces are probably the main way that users will interact with your app. You can create as many user interfaces as you want, and control access to them. This means that you could have one interface for administrators, and another interface for standard users. Furthermore, you can also create mobile user interfaces that are intented for mobile phones. Creating a user interface is done through the left-side menu.

After creating a user interface, it will show up in the left-side menu. Selecting it will take you to the user interface editor.

The user interface consists of three tabs:

• “Views” – Allows you to create, edit and delete views and dialogs. Clicking the settings button (see the image below) brings up a dialog that lets you specify the following settings:
  
  1. Properties – Lets you edit properties that were set when the user interface was created.
  2. Initial Views – The initial view is first view that is shown to users when they view the app through the user interface. For users who do not have access to the initial view, it is also possible to specify backup views
  3. Rights – Specify privileges required to access the user interface.

• “Menu” – Here you can define a menu that is shown on top of all views in the user interface. Menu items can be linked to views of your choice.

• “Theme” – Allows you to define the overarching visual theme of your user interface. A number of precreated themes exist, you can also choose ‘custom’ to define your own theme.

Views are part of a user interface and is the thing that users will see on their phone/computer when interacting with your app. Views typically consists of widgets such as text fields, buttons and images, that display information and enable interaction. Views and their widgets can be styled using CSS, allowing you to design your app to look how you want.

A view may contain one or more forms. Forms can be used by widgets to allow for easy viewing and saving of record data. For more information, see the forms section.

The view editor allows you to define the looks and functionality of a view. On the right side of the view editor is the Widget Palette, from which you can drag widgets into the view. There are a number of different widgets, they are explained more in detail in the [[link: widget section]].

When adding a widget to your view, the widget editor dialog is shown. This dialog allows you to specify the look and behavior of the widget. For example, the widget editor for the button widget lets you specify the text shown on the face of the button, in addition to color and size of the button.

Note: The widget editor dialog is also available by right clicking a widget in the view editor and choosing “edit”.

By clicking the “events” tab in the widget editor you can also specify scripts that should be run when the user clicks the button (see scripts).

A form is an easy way to let users display, create and update records through a view. Every form is coupled to a view, a model, and an optional parent form. The model decides which kind of records the form will be able to display/create/update. By specifying preloaded relations, the record loaded by the form will also come with loaded relations. A form can also have a parent form… TODO.

Before any updates are performed, a form must be submitted. Form submission is done using scripts (in fact, submitting forms is so common that there’s even a QuickAction for it). In some circumstances, every field of a form should not be modifyable by users. In these cases, it is possible to specify fixed attributes. For example, you might have a model with a created_by attribute, which should represent the user that created a specific record. By fixing the user relation attribute to the current user, you will get the desired behavior.

Widgets will automatically detect when a form is present on a view and give you an option to couple them to it. In order for the coupled widgets to be able to display any data, the form must first be loaded with a record. This can be done through scripting, but even easier is to specify the record when navigating to the view. This can be done using the ‘Go to view’ QuickAction. When a record is loaded, submitting the form will update that record. Without any record loaded, submission will attempt to create a new record.

Templates are reusable pieces of text that can use variable values to affect their appearance. The variables are accessed using special handlebars syntax. Apart from variables, the template syntax also provides simple flow control.

To better illustrate how the templates look and function, here’s an example:

Hello, dear {{record.name}}!

This is a mail from {{app.config.companyName}}, writing to let you know of our recent policy changes.
{{#if param.detail}}
These changes include …………
{{/if}}

Best regards,
{{app.config.companyName}}

Template commands are called helpers and are placed between {{double mustaches}}. There are a number of helpers available:

Helpers available in actions (such as send mail or SMS):

Helpers available in views (such as the HTML widget):

Several more helpers are available on the handlebars website.

Data:
Additionally, for templates used in actions, the following data is available:

The messagebus allows you to send and receive asynchronous messages between clients and/or application logic residing in the cloud.

With Appivo you can not only build web- and mobile-applications, you can also manage and build applications for internet-of-things (IoT) devices. This section of the documentation will cover aspects related to this.

Any application built on the Appivo-platform can have IoT-functionality – meaning you can have devices connected to your application that contribute functionality. Examples of this could be a device monitoring the temperature of a room, controlling a doorlock or displaying information on a TV. An application may even have several kinds of devices connected to it and these different device may need to run different code. That’s why an appivo-application can have several deviceprofiles. A deviceprofile is the collection of code required for a certain type of device when being connected to your application.

The deviceprofile contains a set of event-handlers as the programming model for a device is strictly event-based. The platform emits a few fundamental events – such as App.Start and App.Stop – as you might guess these events are emitted when the application starts and stops, on the device that is. Typically you will initialize datastructures and features when the app starts and then clean everything up when it stops.

Devices can also have timers that emit “tick”-events according to a schedule that you determine, this way you can for instance collect data from a sensor at a regular interval. The device may also “listen” for messages being received on messaging-topics – this allows the device to interact with the part of your application running in the cloud, as well as other devices of course.

Devices may also make use of various plugins, there are plugins for interfacing with hardware components  such as I²C, SPI and GPIO – but that’s not all, there is also a plugin for controlling an embedded chrome-browser which can be used to open up web-based user-interfaces that are also part of your application. This makes it very easy to build a digital signage system that can be used with a regular TV.

The DeviceContext is the main interface when interacting with the device. Through it you can get access to hardware-features and general functionality. Notice that when interacting with the database this API is asynchronous and related methods return a Promise. This section of the document provides a description of the DeviceContext API:

Examples

1. Creating a record and storing it in the database.

Note: in this example my SensorValue-model has a relationship to the appliance, so I populate the “appliance_id”-attribute with the appliance-ID.

var sensorData = 7;
var appliance = context.getAppliance();
var record = context.createRecord("SensorValue", {
   "appliance_id": appliance.id,
   "Value": sensorData
});
context.create(record);

2. Getting a record from the database

context.get("Sensor", sensorId).then(function(record) {
   context.log("Got record from database " + record.id);
});

3. Executing a query

context.query("#MyQuery", {
   "threshold": 100
}).then(function(records) {
   for (var i = 0; i < records.length; i++) {
      var record = records[i];
      context.log("Got record " + i + " with id " + record.id);
   }
});

4. Publish a message

context.publish("#mytopic", {
   value: 10,
   status: "OPEN"
});

5. Storing data locally

var counter = compute();
context.setData("counter", counter, "APP");

And retrieving it at a later time:

var counter = context.getData("counter");

{
    pin: string - GPIO pin name (e.g. "GPIO 0"),
    mode: string - INPUT, OUTPUT, INPUT_OUTPUT
}

examples

//Make GPIO pin 0 blink 
context.getModule("gpio").getPin("GPIO 0").blink(500);

Inherits all methods from GPIO Pin

Inherits all methods from GPIO Pin

Inherits all methods from GPIO Pin

Examples

// Get the i2c module
var i2c = context.getModule("i2c");

// Get the device on bus 1, address 0x29
var device = i2c.getDevice(1, 0x29);

// Write 0x30 to the internal register address 0x8A
device.write(0x8A, 0x30);

Examples

// Get the SPI-module
var spi = context.getModule("spi");

// Get the device on CS 0
var device = spi.getDevice(0, 0);

//Write 0x0A, 0x0B, 0xC to the device using CS 0 and store the result (2 bytes)
var bytes = device.write([0x0A, 0x0B, 0x0C]);

//assemble the 2 bytes into a single 16-bit unsigned integer (assuming big endian byte order)
var uInt16 = bytes[0] << 8 | bytes[1];