MCS-4259: add new tutorial (#117)

content/en/SUMMARY.md

@@ -66,5 +66,6 @@
    * [2.21](change_log/2.21.md)
    * [2.22](change_log/2.22.md)
    * [2.23](change_log/2.23.md)
+   * [2.25](change_log/2.25.md)
 
 

content/en/change_log/2.25.md

@@ -0,0 +1,8 @@
+# 2018/07/25
+
+## New Features
+1. Users can be notified directly on MCS web console by adding **Console Alert** in Trigger & Action. [more information](../tutorial/setting_notification)
+
+
+## Resolved Issues
+1. Users might receive 2 mobile push notifications while uploading data points via web console or mobile App.

content/en/change_log/README.md

@@ -1,5 +1,13 @@
 # MCS Change log Summary
 
+
+## 2018/07/25
+
+### v2.25
+
+[Users can be notified directly on MCS web console by adding **Console Alert** in Trigger & Action.](./2.25)
+
+
 ## 2018/05/11
 
 ### v2.23

content/en/tutorial/setting_notification.md

@@ -1,66 +1,133 @@
-# Using Trigger and Action
+# Trigger & Action
 
-## How to add trigger and action
+The Trigger & Action feature is used when you would like to get a notification while the value of a data channel meets certain criteria. 
 
-You can set the trigger and action value for a data channel. When the value passes the limit of the defined range, you will get an email or a Mobile Push notification based on the trigger and action settings. In addition, MCS supports webhook trigger, you can input the URL that you would like to recieve this trigger.
+You can set trigger rules on the following data channels
 
-Please note that MCS only supports trigger and action for integer and float data channel types at the time of writing. Also, only data points uploaded by the device (data points uploaded with deviceKey) will trigger the action. The data points uploaded by user (via web using authentication) will not be triggered.
+1. ON/OFF
+2. Category
+3. String
+4. Hex
+5. Integer
+6. Float
 
+and choose one of the following conditions to apply on that data channel
 
-In the **Prototype** detail page, click the **Trigger & action** tab.
+1. Greater than
+2. Lower than
+3. Equal to
+4. Between
+5. OnChange
 
-![](../images/Trigger/img_trigger_01.png)
+The conditions which must be met before the trigger action executes and there are 4 trigger actions provided.
 
-Click **Add trigger & action** to enter the trigger name and description.
+1. Email
 
-![](../images/Trigger/img_trigger_02.png)
+	Users with access privilege to this device can receive the Email notification, including device owner, administrator and viewer.
+
+2. Mobile Push
 
-Then click **Next** to set the trigger criteria by selecting the data channel you would like to set alert for and enter the value. The rules include greater than, lower then, equal to, and between.
+	Users with MediaTek Cloud Sandbox App installed on his mobile can receive the push notification.
+
+3. Webhook
 
-If there are more than one data channel rules in the trigger criteria, all data channel rules need to be satisfied in order to trigger the action('AND' logic). You can create separate trigger and action rules to use the 'OR' logic.
+	MCS makes an HTTP request to the callback URL that user provided. 
+		
+4. Console Alert
+
+	When that trigger occurs, there is an alert message on web console directly.
 
-![](../images/Trigger/img_trigger_03.png)
 
-Click **Next** to select the trigger action. You can select to get email or Mobile Push notification when the trigger criteria are met. The email and Mobile Push notification will be sent to anyone with the access to the test device.
+## Defining a trigger & action
 
-Furthermore, you are allowed to use MCS pre-defined variables in **Title** and **Content** fileds to capture the real value when the action was triggered. You can find more detail under this page.
+You can set **Trigger & Action rules** for a **prototype** and the rules will be applied to each device under this prototype. In addition, you can edit the **value in condition** at **device** level afterward.
 
+Here are the steps:
 
-![](../images/Trigger/img_trigger_04.png)
+1. In the **Prototype** detail page, click the **Trigger & Action** tab -> **Add trigger & action**.
 
-The test device will inherit all the trigger and action from its parent prototype. In a test device, you can only change the value of the trigger criteria or select to switch on or off a specific trigger and action.
+	![](../images/Trigger/img_trigger_01.png)
+
+2. Provide the necessary information in the **Add trigger & action** dialog.
+
+	Step 1: The **trigger name** will display in the **console alert** when it is triggered.
+	![](../images/Trigger/img_trigger_02.png)
+
+	Step 2: The match condition is **AND** if there are multiple criteria set. That means you have to upload these data points **in one payload** and all of them match the conditions. 
+	![](../images/Trigger/img_trigger_03.png)
+
+	Step 3: At least one action need to be selected. We will explain more about each action later.
+	![](../images/Trigger/img_trigger_04.png)
+
+
+The device inherits all the trigger & action rules from its prototype. However, you can still change the value of the trigger criteria and enable or disable trigger & action rules for a device.
 
 ![](../images/Trigger/img_trigger_05.png)
 
-## Setting trigger and action for different mobile devices
 
-If you have multiple mobile devices, MCS allows you to set which mobile devices will receive the mobile push notification. You can find the setting in two places:
+Please note, only data points uploaded by the device (with **deviceKey in HTTP header** or via **MQTT**) can trigger the action. The action will NOT be triggered by the UI operation on the web console.
+
 
-1. In the **User Profile** page, you can switch on or off all the notification from MCS to a specific mobile device.
-2. In the **Test device** page, you can switch on or off all notification from a specific test device to a specific mobile device.
+## More about Trigger Actions
+### Configuring the Mobile Push
 
-In the **User Profile** page, you can see a mobile list that includes all user's mobile devices with MCS app installed. You can use the **Swith** to control which mobile device will receive notifications from MCS.
+If you have multiple mobile devices, you can choose which mobile devices can receive the mobile push notification. You can find the setting in two places:
+
+1. In the **User Profile** page, you can switch on or off **all the mobile push** to a mobile device.
+2. In the **Test Device** page, you can switch on or off all **mobile push for a test device** to a mobile device.
+
+In your **User Profile** page, there is a mobile list that includes all your mobile devices with MCS App installed. You can use the **Switch** to control which mobile device can receive mobile push from MCS.
 
 ![](../images/Trigger/img_trigger_06.png)
 
-In the **Trigger & action** tab in the test device page, expand the **Manage your action** section and you will see a list of all user's mobile devices with MCS app installed. You can use the **switch** here to control which specific mobile device will receive the notification from this test device.
+In the **Trigger & Action** tab in the test device page, expand the **Manage your action** section and there is a mobile list that includes all your mobile devices with MCS App installed. You can use the **Switch** here to control which mobile devices can receive the mobile push for this test device.
 
 ![](../images/Trigger/img_trigger_07.png)
 
 
+### Configuring the Webhook
 
-# Set up a webhook trigger
-
-To set up a webhook trigger, you have to select the **webhook** as the action in the Trigger & action tab in the prototype. And input the url that you would like to get the webhook trigger.
+There is no extra setting for webhook. To use webhook trigger, you only have to select the **webhook** as the action in the trigger & action setting and provide the callback URL that MCS makes an HTTP request to.
 
 ![](../images/Trigger/img_trigger_08.png)
 
-There is a Test button for you to test if the trigger has been sent to the url. The device name, deviceId and the triggered value will be sent to the triggered url.
+There is a Test button for you to test if the trigger has been sent to the URL. The device name, deviceId and the triggered value will be sent to the triggered URL.
+
+
+### Configuring the Console Alert
+
+You have to specify the severity level while configuring console alert in Trigger & Action.
+
+![](../images/Trigger/img_trigger_13.png)
+
+When that trigger occurs, the console alert with severity information will show on the web console immediately. It is displayed on the following page.
+
+1. Data Channel Card 
+
+	You can expand the alert message bar to see more information, including **trigger name** and **alert time**. In this case, a data was uploaded on "2018-07-19 11:36" and triggered a rule named "Water is too hot". 
+
+	After you click **Dismiss**, this alert will be cleared. You won't see this alert until the new data is uploaded and the trigger rule is matched.
+
+	![](../images/Trigger/img_trigger_10.png)
+
+2. Test Device List
+
+	It always displays the alert with **highest severity** right this moment. 
+
+	Take the previous case for example. You will see "High" alert on the card, if "High" alert is dismissed, and then it shows "Medium" alert instead.
+
+	![](../images/Trigger/img_trigger_11.png)
+
+3. Scene
+
+	The presentation logic is the same as Device List.
+
+	![](../images/Trigger/img_trigger_12.png)
+
 
 
-MCS supports customized webhook body message. You can also use the pre-defined variables. For the customized variables, please refer to the following paragraph.
 
-# Use variables in notification message
+## Use variables in notification message
 
 MCS provides pre-defined variables which can be used in both Title and Content fileds. These variables will be replaced with real values when the action is triggered. The pre-defined variables include:
 

content/zh-CN/SUMMARY.md

@@ -66,4 +66,5 @@
    * [2.21](change_log/2.21.md)
    * [2.22](change_log/2.22.md)
    * [2.23](change_log/2.23.md)
+   * [2.25](change_log/2.25.md)
 

content/zh-CN/change_log/2.25.md

@@ -0,0 +1,8 @@
+# 2018/07/25
+
+## 新功能
+1. 在**触发动作**中，新增**网页警示**，当触发条件符合时，使用者能在网页上看到警示内容。[详细介绍](../tutorial/setting_notification)
+
+
+## 问题修复
+1. 在 MCS 网页或是手机应用程式操作资料通道时，有时候会触发两笔手机推播通知。

content/zh-CN/change_log/README.md

@@ -1,5 +1,12 @@
 # MCS 更新日志总览
 
+## 2018/07/25
+
+### v2.25
+
+[新增**网页警示**功能，使用者可直接在网页上看到触发内容。](./2.25)
+
+
 ## 2018/05/11
 
 ### v2.23
@@ -115,4 +122,4 @@
 
 ### v2.5
 
-[导入繁体中文以及简体中文版本，以及提供触发条件与动作功能。](./2.5)
+[导入繁体中文以及简体中文版本，以及提供触发条件与动作功能。](./2.5)

content/zh-CN/tutorial/setting_notification.md

@@ -1,65 +1,127 @@
-# 设定触发条件和动作
+# 触发条件与动作
 
-##如何新增触发条件和动作
+您可以设定触发条件和动作，当特定资料通道回传的值符合您所设定的条件，系统将会发出通知提醒。 
 
-您可以设定触发条件和动作，当特定资料通道回传的值超过您所设定的范围时，系统将会发出电子邮件或是手机推送通知。您可以自行选择要收到电子邮件或是手机推送通知。此外，MCS 也支援 webhook 触发，您可以输入欲收到处发通知之 URL。
+以下是支援设定触发条件的**资料通道**：
 
-请注意，目前 MCS 的通知只限定使用整数或是浮点数类型的资料型态。并且，只有透过装置上传的资料点（上传资料点时带有 deviceKey）会触发动作。使用者透过 MCS 网页上传之资料点（不带有 deviceKey）将不会触发。
+1. 开关
+2. 分类
+3. 字串
+4. 十六进位值
+5. 整数
+6. 浮点数
 
-当您点入产品原型页面后，点选**触发条件和动作分页**。
+并可套用以下的**条件**：
 
-![](../images/Trigger/img_trigger_01.png)
+1. 大于
+2. 小于
+3. 等于
+4. 介于～之间
+5. 数值异动
 
-点击**新增触发条件和动作**来新增一个触发条件和动作, 输入您的触发条件名称和描述。
+当资料通道上传的数值符合设定条件时时，会触发通知动作。以下是四种支援的通知**动作**：
 
-![](../images/Trigger/img_trigger_02.png)
 
-点击下一步来设定触发条件。选择您要设定触发条件的资料通道并且给予触发条件值。触发条件包含大于，小于，等于，和特定范围之间。
+1. 电子邮件
 
-您可以在同一个通知条件中，设定多个资料通道。此时，多个资料通道条件都要符合(且逻辑)，系统才会发出通知。若您想要单一条件符合(或逻辑)就收到通知，您就须设定多个通知条件。
+	有权限能访问这个装置的使用者，皆能收到电子邮件通知，包括装置的拥有者、管理者与一般检视。
+
+2. 手机推播
 
-![](../images/Trigger/img_trigger_03.png)
+	您必须先安装 MediaTek Cloud Sandbox 手机应用程式，并且登入 MCS 帐号。	
 
-点击下一步来设定触发动作。您可以选择使用电子邮件或是手机推送通知。通知将会被发送给每个有此装置权限的使用者。
+3. Webhook
 
-此外，您可以在名称与内容栏位中使用 MCS 定义的变数来获取触发动作发生当下设备所产生或纪录的真实数值。
+	MCS 会发送一个 HTTP 请求到您指定的网址（Callback URL）。
+		
+4. 网页警报
+
+	当触发条件成立时，在 MCS 网页上会显示相关的提醒，包含触发警报的严重等级。
+
 
+## 设定触发条件与动作
 
-![](../images/Trigger/img_trigger_04.png)
+您可以在**产品原型**页面下设定**触发条件与动作**，此触发规则会套用在此原型下的所有装置。随后，您可以在各个**装置**底下，修改条件的**触发数值**。
 
-您在产品原型中设定的触发条件和动作，会被产品原型下所有的测试装置所继承。在测试装置中，您只能更改触发条件的值或是选择打开或是关闭此触发条件和动作。
+操作步骤如下：
+
+1. 当您点入产品原型页面后，点选**触发条件和动作**分页 -> 点击**新增触发条件和动作**。
+
+![](../images/Trigger/img_trigger_01.png)
 
+2. 在**新增触发条件和动作**视窗中，填入必要的资讯。
+
+	步骤一：**触发条件名称**之后将会显示于**网页警报**的讯息中。
+	![](../images/Trigger/img_trigger_02.png)
+
+	步骤二：您可设定多个比对条件，当这些**条件同时成立**时（**AND 逻辑**），则会触发通知。请注意，要让条件同时成立，您必须将此条件有用到的资料通道数值**同时上传**到 MCS，意即写在同个 HTTP 上传的请求当中。
+	![](../images/Trigger/img_trigger_03.png)
+
+	步骤三：至少选择一个**触发动作**，当条件成立时，发送通知。本章后面会针对触发动作有更详细的介绍。
+	![](../images/Trigger/img_trigger_04.png)
+
+
+您在产品原型中设定的触发条件和动作，会被产品原型下所有的测试装置所继承。在测试装置中，您只能更改触发条件的值或是选择打开或是关闭此触发条件和动作。
 ![](../images/Trigger/img_trigger_05.png)
 
-##替不同手机设定触发条件和动作
+请注意，只有透过装置上传的资料点（上传资料点时，在 HTTP 表头带有 **deviceKey** 或是透过 **MQTT** 协定发布资料）才会触发动作。使用者透过 MCS 网页操作资料通道而产生的资料点将不会触发。
+
+## 触发动作详细介绍
+### 设定手机推播
 
-若使用者有多个手机装置， MCS能夠提供使用者設定是否每隻手機裝置都要收到手機推播通知。使用者能於兩個地方設定：
+若使用者有多个手机装置，MCS 能够提供使用者设定是否每只手机装置都要收到手机推播通知。使用者能于两个地方设定：
 
-1. 在**个人档案**页面中，设定是否手机要收到全部来自 MCS 的推播通知。
-2. 在**测试装置**页面中，设定是否手机要收到来自特定测试装置的推播通知。
+1. 在**个人档案**页面中，设定是否手机要收到**全部**来自 MCS 的推播通知。
+2. 在**测试装置**页面中，设定是否手机要收到来自**特定测试装置**的推播通知。
 
-在**个人档案**页面中，您可以看到所有您有安装 MCS 手機應用程式的手機列表。您可在此設定是否特定手機要收到或不收到**全部**來自 MCS 的推播通知。
+在**个人档案**页面中，您可以看到所有您有安装 MCS 手机应用程式的手机列表。您可在此设定是否每只手机要收到或不收到**全部**来自 MCS 的推播通知。
 
 ![](../images/Trigger/img_trigger_06.png)
 
-在**測試裝置**頁面中，展開**管理您的觸發動作**，您可以看到所有您有安裝 MCS 手機應用程式的手機列表。您可在此設定是否特定手機要收到或不收到特定測試裝置的推播通知。
+在**测试装置**页面中，展开**管理您的触发动作**，您可以看到所有您有安装 MCS 手机应用程式的手机列表。您可在此设定是否特定手机要收到或不收到**特定测试装置**的推播通知。
 
 ![](../images/Trigger/img_trigger_07.png)
 
+### 设置 Webhook 
 
-# 设定一个 webhook 触发动作
+要使用 webhook 触发动作，您只需要在设定触发条件时，选择 webhook 作为触发动作，并且输入您欲收到此触发通知之网址。当触发条件成立时，MCS 会发送一个 HTTP 请求到您提供的网址。
 
-若要设定一个 webhook 触发动作，您首先需要在产品原型页面中的触发条件与动作分页中，新增一个 webhook 之触发条件与动作。并且输入您欲收到此触发通知之网址。
+![](../images/Trigger/img_trigger_08.png)
 
+当您选择 webhook 触发动作后，您可以使用测试按钮，来测试是否通知有被送出。送出之资讯包含 装置名称, device ID 和触发值。
 
-![](../images/Trigger/img_trigger_08.png)
+### 设定网页警报
+
+当您在触发条件与动作中设定网页警报时，也必须指定此警报的严重性等级。
+
+![](../images/Trigger/img_trigger_13.png)
+
+当触发条件成立，网页警报讯息会立即出现在网页上，并显示**严重性等级**等资讯。网页警报会出现在以下三个页面：
+
+1. 资料通道卡片 
+
+	当资料通道的数值符合触发条件，该资料通道上便会出现网页警告标签。展开后可看到更详细的触发资讯，包括**触发条件名称**与**警告发生时间**。在此范例中，此资料点是于 "2018-07-19 11:36" 上传并触发一个名叫 "Water is too hot" 的触发条件。
+
+	当你点击**解除**之后，这个警告则会被解除不会显示在网页上，直到下次您的装置在上传符合此触发条件的资料点。
+
+	![](../images/Trigger/img_trigger_10.png)
+
+2. 测试装置列表
 
-当您选择 webhook 触发动作后，您可以使用测试按钮，来测试是否通知有被送出。送出之资讯包含装置名称, deviceId 和触发值。
+	在测试装置列表中，**严重性最高**的警报会显示在测试装置的卡片上。
+
+	以上面的范例来说，当测试装置底下有两个资料通道皆触发了网页警报，一个严重等级为 "High" 另一个为 "Medium"，则装置卡片上的警报等级，会显示 "High"。当 "High" 的警报解除后（可能是您按下了“解除”按钮，或是重新上传一个不符合触发条件的资料点），则会显示下一等级的警报 "Medium"。
+
+	![](../images/Trigger/img_trigger_11.png)
+
+3. 场景图
+
+	场景图中，警报标签的呈现方式与测试装置列表ㄧ样。
 
-MCS 支援使用者可自定 webhook 的传递内容。您亦可以可以在此使用变数。关于使用的变数细节，请参考以下章节。
+	![](../images/Trigger/img_trigger_12.png)
 
-# 在通知内容中使用变数
 
+## 在通知内容中使用变数
 MCS 预先定义了多个变数让您可以在通知的名称与内容栏位中使用，这些变数代表的是动作被触发时，当下的真实数据。目前支援的变数包含有：
 
 * **${deviceId}**: 设备的 ID