Documentation

Introduction

Welcome to Qmiix platform! As a platform user, you can create simple and advanced miixes and achieve near real-time execution of those miixes. In order to build the best possible apps on Qmiix, you should get familiarised with Qmiix terminology.

Triggers:

Think of triggers as events on your app. Some example triggers are “Any new post” or “New photo added to album”.

Trigger Essentials:

Think of trigger essentials as a “filter” for the data requested from a trigger. For example, when a user selects the trigger “New photo added to album,” they will be asked for the album name.

Elements:

The attributes emitted from a given trigger are called elements. For the trigger “New photo added to album,” there would be elements for “PhotoURL” and “TakenAt.”

Actions:

Think of action as a work that Qmiix initiates as a result of events on your app. Some example actions include “Create post” or “Upload photo” or “Turn on lights.”

Action Essentials:

While creating a Miix user fills action's essentials with data, usually including the elements provided by the trigger. Think of action essential as a form field. For the action “Create post,” there would be one action essential for “Title” and another for “Post body.”

Overview

Qmiix defines a clear and concise protocol which your app's API will implement. Each trigger and action for your app will map 1-to-1 to an API endpoint on your app built specifically for Qmiix. Trigger endpoints will be event streams that Qmiix will poll for new data. Conversely, action endpoints will be writable endpoints that Qmiix will send data to. For services that use OAuth, Qmiix is fully compatible with a couple of the common flavors of OAuth 2.0. Partner apps should be fully compatible with our partner app API requirements. Check Partner App API for more details on Qmiix partner API requirements. Qmiix also provides sets of public management API for partner app to update data in Qmiix. Check Public Management API for more details.

After partner app APIs has fully implemented, partner could use endpoint testing tool in the Qmiix Partner to test that the APIs are compatible with Qmiix protocol. Check Endpoint Testing for more details on setting up testing with partner app's API.

This document will guide you through the ideal workflow for adding your app to Qmiix.

1. Setup your development environment

You will be creating Qmiix-specific endpoints that correspond to each trigger and action in your app. You can follow Qmiix's protocol guide for creating endpoints.

2. Create your app and connect to Qmiix

When you login for the first time after your partner admin account is created, you would be redirected to “Create Your First App with Qmiix” page where you could use “Hello World” link to create Hello World app or you can create new app using “CREATE NEW APP” button as shown below.

While you creating new app fill the ‘App Name’ and ‘App ID’ app details and click “CREATE” button.

You can fill other details later by selecting the app from ‘My Apps’ page. But be sure to fill out the API URL Prefix.

Qmiix provides a testing tool which you will be using to build your endpoints. The first endpoint you will be building is /status, which will help you to verify whether Qmiix can reach your app.

Build the App Status endpoint. When it's ready, navigate to 'Endpoint Tests' under 'API Management' and run the endpoint tests. You willl see a passing status spec which indicates that Qmiix was able to reach your app successfully.

3. Define app properties, triggers and actions

App properties:

Fill out general information like app name, description, webpage URL etc., about app under general properties.

Upload logo for your app, choose brand color, and upload app screenshots under branding properties.

App details page could have a button “View more” and redirect users to their defined URL. This is for marketing purpose you could define some URL that is related to your product and provide here.

Define the triggers, trigger's essentials, trigger's elements, usage and miix template.

Trigger:

To create a trigger use “CREATE NEW TRIGGER” button in Triggers page under API management in partner console. Fill out trigger name, description and valid endpoint details. Every trigger requires a unique API endpoint.

Trigger Essentials:

Once trigger is created successfully, provide one or more trigger essentials using “ADD ESSENTIAL”. Trigger essentials can be private or public. Private essentials are not shown to the user while using a trigger. Public essentials can be used by the user. It supports various input types such as text input, drop-down list, location, date, time, time zone, list of text, radio button and check box. The trigger essential input type determines the validation rule and required metadata. Trigger essentials can have dynamic options and dynamic validation. Each dynamic option and validation requires a unique endpoint.

Trigger Elements:

Next you need to create trigger elements. Each trigger is required to have atleast one trigger element. A user will use these individual elements provided by the trigger and will use them to fill in an action’s action essentials. To create trigger element use “ADD ELEMENT” link as shown

Usage:

Every trigger can have usage which can be combination of trigger essentials and custom text. When user creates a miix from the scratch, Qmiix suggests a title based on the trigger and actions they used, using the pattern “[trigger usage ]+[action1 usage ]+[action2 usage ]+[action3 usage ]+[action4 usage ]+[action5 usage]”

Miix Template:

This is example content your trigger will automatically pre-populate in the miix’s action essential(s) when user create miixes from the scratch. While filling these fields think about how your users would want to use the information about the trigger in the various action categories.

Define actions, action's essentials and usage.

Actions:

To create actions use “CREATE NEW ACTIONS” button in Actions page under API management in partner console. Fill out action name, description and valid endpoint details. Every action requires a unique API endpoint.

Action Essentials:

Once action is created successfully, provide one or more action essentials using “ADD ESSENTIAL”. Action essentials can be private or public. Private essentials are not shown to the user while using a trigger. Public essentials can be used by the user. It supports various input types such as text input, drop-down list, location, date, time, time zone, list of text, radio button and check box. The action essential input type determines the validation rule and required metadata. Action essentials can have dynamic options and dynamic validation. Each dynamic option and validation requires a unique endpoint.

Usage:

Every action can have usage which can be combination of action essentials and custom text. When user creates a miix from the scratch, Qmiix suggests a title based on the trigger and actions they used, using the pattern “[trigger usage ]+[action1 usage ]+[action2 usage ]+[action3 usage ]+[action4 usage ]+[action5 usage]”

Follow the following principles in order to choose the right trigger and action functionality for your app:

Start with some initial set of triggers and actions and expand them later. Triggers like “Any new photo” or “New post by you” tend to get broader use than ones like “Any new photo with tag” or “New post by you in category.”

Better to use less number of essentials. Instead of one trigger “Ignition turned on or off” with an essential for “On or off?”, it’s much more powerful to have two triggers: “Ignition turned on” and “Ignition turned off.”

Remember, you can easily make changes before launching.

4. Essentials Priority

Qmiix partner admin could assign order for trigger essentials and action essentials while managing triggers and actions under API management in Qmiix partner portal. Partner could use the up and down arrows to change the order or priority for essentials as shown below.

By changing the order you are actually setting the dependency number for essential (default is 0). When you call dynamic validation or dynamic options, the value of the essential assigned with smaller dependency number than the other essentials will be carried in the request to the dynamic validation api or dynamic options api.

5. Use Qmiix's endpoint testing tool

Qmiix's endpoint testing tool will enable you to rapidly develop your endpoints that are compatible with Qmiix.

You can find the endpoint testing tool under “API Management” on your app dashboard. Use this tool to test your trigger and action endpoints that you built referring our protocol/ Partner App API reference document.

The workflow of the endpoint testing tool is straightforward.

1. Qmiix makes request to /status and check whether it can reach the app.

2. Qmiix makes request to /test/setup. This endpoint's response provides a valid access token for a user as well as sample values for each trigger and action essentials in your app.

3. Qmiix uses the access token (if applicable) and sample values to make test requests against your API

6. Set up OAuth integration

Qmiix is fully compatible with Oauth 2.0. For more details of our implementation, please check App Connection of our protocol reference.

Once you define authentication settings in Authentication page under API management, use the connection testing tool under API management on your app dashboard to ensure the integration is working properly.

Authentication

Connection Tests

7. Implement the Realtime API

With Qmiix's Realtime API, you can have miixes involving user-oriented triggers from your app run near-instantly.

See Realtime API for instructions on implementing Realtime.

Note: To ensure a great miix experience for your users, triggers are required to use the Realtime API if a user would expect its miixes to run in realtime.

8. Test your app end to end

It is advisable that you create miixes using each trigger and action from your app on Qmiix test your miixes to ensure that things work as expected. Your user also will have special preview access to use the app on Qmiix.

9. Add app administrators

If we need to contact you about the app, we will use the information you provided under the App Admins section in the partner portal. To add/provide app admins information go to “App Admin” tab under Roles and Permissions user menu.

10. Cloned App

You could clone app and make necessary changes in the cloned app and submit for review in order to make changes in the triggers and actions of the published app. The cloned app with the modifications will be reviewed by the Qmiix Admin. Only if the Qmiix Admin allows, the existing triggers and actions of the published app can be changed or updated.

Please follow the below steps if you wanted to edit triggers and actions of the published app.

• Click the clone icon

  

• Once the app is cloned, you will be redirected to the edit page, the new cloned app will have the name _cloned. You can go ahead and make necessary changes required. Please note that the following operations are not allowed for cloned app.

• Edit Existed Old Trigger.

• Edit (Add, Delete) Trigger Essential of Existed Old Trigger.

• Edit (Add, Delete) Trigger Element of Existed Old Trigger.

• Edit (Add, Delete) Miix Template of Existed Old Trigger.

• Edit Existed Action.

• Edit (Add, Delete) Action Essential of Existed Old Action.

• Please note that once the first clone is made for your app, then the clone icon will be disabled. So you can’t clone more than once till your changes of first clone is approved and changes are merged to the published app. But you can delete the cloned app under configuration and can clone new one again.

• You can submit the cloned app to Qmiix Admin for merge request after modifications are done and all the checklist status are turned to green.

• Upon receiving the submission, Qmiix Admin can use admin portal to review the cloned app and provide the feedbacks. Partners need to rectify the feedback in order to make the changes to the published app.

• When the submission is approved by Qmiix Admin, you cannot not edit the cloned app further.

• After published app are updated, all affected miixes will be removed and all the user with affected miixes would be sent notifications of the change.

• After the app is published, the cloned app will be removed automatically.

11. Submit your app for review

Service Checklist:

Partner admin or App admin has an option to review the checklist by clicking “RUN CHECKLIST” button. This is an automated process, it checks whether all the required items are fulfilled in order to publish the app. Once all the items in the checklist are clear, the partner admin can submit the app for QNAP’s review.

Review:

Partner admin or App admin has an option to manually review all the details provided for the app and provide feedback for each fields.

Publish:

Once you're confident about your app, then go ahead and submit it! You can find the 'Submit for Review' link in the Publish page under Review & Publish. The Qmiix Admin will review the app manually using Admin portal and provide some feedback about the submitted app.

12. Health and Analytics

Health:

Partner admin or app admin could check the health of their app for all the requests. The endpoint success and failure ratio chart will provide details on the success and failure ratio for all the API access. You could also use dropdown filters to specify specific request type and duration. The pink and blue line indicates the success-failure ratio for the duration mentioned.

You could check the error codes, expand each error logs of all API access and analyse the request-response to find out what went wrong in case of app’s endpoints failures.

Analytics:

Partner admin or app admin could access app analytics for their apps. They could view scoreboard, various charts, table summary and map etc., which provides details on summary of total active miixes, total active miixes increased in last 24 hours, total connected users, total connected users increased in last 24 hours, user trends, miix trends, miix activity, miix distribution, app distribution and user distribution.