openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From houshen...@apache.org
Subject [incubator-openwhisk-wskdeploy] branch master updated: Programming Guide - part11 - sequence example (#591)
Date Thu, 05 Oct 2017 16:36:00 GMT
This is an automated email from the ASF dual-hosted git repository.

houshengbo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git


The following commit(s) were added to refs/heads/master by this push:
     new bd87a92  Programming Guide - part11 - sequence example (#591)
bd87a92 is described below

commit bd87a926162b274e604b88829194d8d5892f7190
Author: Matt Rutkowski <mrutkows@us.ibm.com>
AuthorDate: Thu Oct 5 11:35:58 2017 -0500

    Programming Guide - part11 - sequence example (#591)
    
    * Initial markdown and example code for env. var. example.
    
    * Initial markdown and example code for env. var. example.
    
    * Initial markdown and example code for env. var. example.
    
    * Initial markdown and example code for env. var. example.
    
    * Initial markdown and example code for env. var. example.
    
    * Initial markdown and example code for env. var. example.
    
    * Initial markdown and example code for env. var. example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add runtime version example.
    
    * Add bottom nav. to all spec. markdown pages.
    
    * Add bottom nav. to all spec. markdown pages.
    
    * Add bottom nav. to all spec. markdown pages.
    
    * Add bottom nav. to all spec. markdown pages.
    
    * Add bottom nav. to all spec. markdown pages.
    
    * Add bottom nav. to all spec. markdown pages.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Add sequence example.
    
    * Update sequence Actions to preform more tasks.
    
    * Update sequence Actions to preform more tasks.
    
    * Update sequence Actions to preform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * Update sequence Actions to perform more tasks.
    
    * removed unneeded image files
    
    * adjusted example desc.
---
 README.md                                  |  11 +-
 docs/examples/manifest_sequence_basic.yaml |  36 +++++
 docs/examples/src/member_equip.js          |  29 ++++
 docs/examples/src/member_join.js           |  24 ++++
 docs/examples/src/member_process.js        |  31 +++++
 docs/programming_guide.md                  |   4 +-
 docs/wskdeploy_action_env_var_parms.md     |   2 +-
 docs/wskdeploy_sequence_basic.md           | 208 +++++++++++++++++++++++++++--
 docs/wskdeploy_triggerrule_basic.md        |   2 +-
 tests/dat/actions/dump_params.js           |   4 +-
 10 files changed, 331 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 1612f40..e564932 100644
--- a/README.md
+++ b/README.md
@@ -7,17 +7,18 @@
 
 You can use this in addition to the OpenWhisk CLI.  In fact, this utility uses the [OpenWhisk
"Go" Client](https://github.com/apache/incubator-openwhisk-client-go) to create its HTTP REST
calls for deploying and undeploying your packages.
 
-# Here are some quick links for:
+## Here are some quick links for:
 
-- [Building the project](#building-the-project) - download and build the GoLang source code
+- [Downloading wskdeploy](#downloading-released-binaries) - released binaries for Linux,
Mac OS and Windows
 - [Running wskdeploy](#running-wskdeploy) - run wskdeploy as a binary or Go program
-- [Downloading released binaries](#downloading-released-binaries) - for Linux, Mac OS and
Windows
-- [Writing Package manifests](docs/programming_guide.md#wskdeploy-utility-by-example) - step-by-step
guide on writing Package Manifest and deployment files for ```wskdeploy```
+- :eight_spoked_asterisk: [Writing Package Manifests](docs/programming_guide.md#wskdeploy-utility-by-example)
- a step-by-step guide on writing Package Manifest files for ```wskdeploy```
+- [Building the project](#building-the-project) - download and build the GoLang source code
 - [Contributing to the project](#contributing-to-the-project) - join us!
 - [Debugging wskdeploy](docs/wskdeploy_debugging.md) - helpful tips for debugging the code
and your manifest files
 - [Troubleshooting](#troubleshooting) - known issues (e.g., Git)
 
-<!-- ----------------------------------------------------------------------------- -->
+---
+
 ## Building the project
 
 ### GoLang setup
diff --git a/docs/examples/manifest_sequence_basic.yaml b/docs/examples/manifest_sequence_basic.yaml
new file mode 100644
index 0000000..bfe082c
--- /dev/null
+++ b/docs/examples/manifest_sequence_basic.yaml
@@ -0,0 +1,36 @@
+# Example: processing data in a sequence
+package:
+  name: fellowship_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    member_join:
+      function: src/member_join.js
+      inputs:
+        name:
+          type: string
+          description: name of person
+          default: unknown
+        place:
+          type: string
+          description: location of person
+          default: unknown
+        job:
+          type: string
+          description: current occupation
+          default: 0
+      outputs:
+        member:
+          type: json
+          description: member record
+    member_process:
+      function: src/member_process.js
+      inputs:
+        member: {}
+    member_equip:
+      function: src/member_equip.js
+      inputs:
+        member: {}
+  sequences:
+    fellowship_membership:
+      actions: member_join, member_process, member_equip
diff --git a/docs/examples/src/member_equip.js b/docs/examples/src/member_equip.js
new file mode 100644
index 0000000..8717f03
--- /dev/null
+++ b/docs/examples/src/member_equip.js
@@ -0,0 +1,29 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
+const equipmentMap = new Map([
+    ['gentleman', 'ring'],
+    ['wizard', 'staff'],
+    ['archer', 'bow'],
+    ['knight', 'sword'],
+    ['barbarian', 'club'],
+    ['warrior', 'axe'],
+    ['thief', 'dagger'],
+    ['gardener', 'rope'],
+    ['squire', 'shortsword'],
+    ['scout', 'horn'],
+]);
+
+function main(params) {
+    console.log("params: " + JSON.stringify(params, null, 4));
+
+    if(params.member && typeof params.member === "object"){
+        // Equip the member based upon their occupation
+        member = params.member;
+        member.item = equipmentMap.get(member.occupation) || "None";
+    }
+    else
+        throw new Error("Invalid parameter: 'member'. type="+typeof(member) + ", expected
object).")
+
+    console.log("member: " + JSON.stringify(member, null, 4));
+    return { member: member };
+}
diff --git a/docs/examples/src/member_join.js b/docs/examples/src/member_join.js
new file mode 100644
index 0000000..77cea8d
--- /dev/null
+++ b/docs/examples/src/member_join.js
@@ -0,0 +1,24 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
+
+/*
+ * Join the fellowship
+ */
+function main(params) {
+    console.log("params: " + JSON.stringify(params, null, 4));
+    var member = {name:"", place:"", region:"", occupation:"", joined:"", organization:"",
item:"" };
+
+    // The organization being joined is fixed
+    member.organization = "fellowship";
+
+    // Fill in a member record from parameters
+    member.name = params.name;
+    member.place = params.place;
+    member.occupation = params.job;
+
+    // Save the current timestamp when we created the member record
+    member.joined = Date.now();
+
+    console.log("member: " + JSON.stringify(member, null, 4));
+    return { member: member };
+}
diff --git a/docs/examples/src/member_process.js b/docs/examples/src/member_process.js
new file mode 100644
index 0000000..af3ac90
--- /dev/null
+++ b/docs/examples/src/member_process.js
@@ -0,0 +1,31 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor
+// license agreements; and to You under the Apache License, Version 2.0.
+const regionMap = new Map([
+    ['Shire', 'Eriador'],
+    ['the Shire', 'Eriador'],
+    ['Hobbiton', 'Eriador'],
+    ['Bree', 'Eriador'],
+    ['Rivendell', 'Eriador'],
+    ['Minas Tirith', 'Gondor'],
+    ['Esgaroth', 'Rhovanion'],
+    ['Dale', 'Rhovanion'],
+    ['Lake Town', 'Rhovanion'],
+    ['Minas Morgul', 'Mordor'],
+]);
+
+function main(params) {
+    console.log("params: " + JSON.stringify(params, null, 4));
+
+    if(params.member && typeof params.member === "object"){
+        // Augment the member (record) created in the previous Action
+        member = params.member;
+        member.region = regionMap.get(member.place) || "unknown";
+        member.date = new Date(member.joined).toLocaleDateString();
+        member.time = new Date(member.joined).toLocaleTimeString();
+    }
+    else
+        throw new Error("Invalid parameter: 'member'. type="+typeof(member) + ", expected
object).")
+
+    console.log("member: " + JSON.stringify(member, null, 4));
+    return { member: member };
+}
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index 1e91eee..e066878 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -31,7 +31,9 @@ Each example shows the "code", that is the Package Manifest, Deployment
file and
   - [Typed Parameters](wskdeploy_action_typed_parms.md#actions) - declare named input and
output parameters on an Action with their types.
   - [Advanced Parameters](wskdeploy_action_advanced_parms.md#actions) - input and output
parameter declarations with types, descriptions, defaults and more.
   - [Using Environment Variables](wskdeploy_action_env_var_parms.md#actions) - reference
values from environment variables and bind them to an Action's input parameters.
-- Trigger and Rule examples.
+- Sequences examples
+  - [Sequencing Actions together](wskdeploy_sequence_basic.md#sequences) - sequence three
actions together to process and augment data.
+- Trigger and Rule examples
   - [Basic Trigger and Rule](wskdeploy_triggerrule_basic.md#triggers-and-rules) - adding
a basic trigger and rule to the advanced Parameter "hello world".
   - [Binding parameters in a Deployment file](wskdeploy_triggerrule_trigger_bindings.md#triggers-and-rules)
- using a deployment file to bind values to a Trigger’s parameters and applying them to
a compatible manifest file.
 
diff --git a/docs/wskdeploy_action_env_var_parms.md b/docs/wskdeploy_action_env_var_parms.md
index 66ad891..c3c0cdc 100644
--- a/docs/wskdeploy_action_env_var_parms.md
+++ b/docs/wskdeploy_action_env_var_parms.md
@@ -89,7 +89,7 @@ For convenience, the Actions and Parameters grammar can be found here:
   <tr>
     <td><a href="wskdeploy_action_advanced_parms.md#actions">&lt;&lt;&nbsp;previous</a></td>
     <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
-    <td><a href="wskdeploy_triggerrule_basic.md#triggers-and-rules">next&nbsp;&gt;&gt;</a></td>
+    <td><a href="wskdeploy_sequence_basic.md#sequences">next&nbsp;&gt;&gt;</a></td>
   </tr>
 </table>
 </div>
diff --git a/docs/wskdeploy_sequence_basic.md b/docs/wskdeploy_sequence_basic.md
index 6641d76..a93a5f0 100644
--- a/docs/wskdeploy_sequence_basic.md
+++ b/docs/wskdeploy_sequence_basic.md
@@ -2,40 +2,226 @@
 
 ## Creating a basic Action sequence
 
-This example
+OpenWhisk supports creating a new, named composite action from sequencung multiple, compatible
Actions.
 
 This example:
-- TBD
+- Shows how to use a Manifest to sequence three actions together to:
+  - accept raw parameter data, creating a structured record from it
+  - process the initial data and enhance it
+  - augment the data via the sequenced actions
 
 ### Manifest File
 
-#### _Example: input and output parameters with explicit types and descriptions_
+#### _Example: Composing 3 actions into a sequence._
 ```yaml
+# Example: processing data in a sequence
+package:
+  name: fellowship_package
+  ...
+  actions:
+    member_join:
+      function: src/member_join.js
+      inputs:
+        name:
+          type: string
+          description: name of person
+          default: unknown
+        place:
+          type: string
+          description: location of person
+          default: unknown
+        job:
+          type: string
+          description: current occupation
+          default: 0
+      outputs:
+        member:
+          type: json
+          description: member record
+    member_process:
+      function: src/member_process.js
+      inputs:
+        member: {}
+    member_equip:
+      function: src/member_equip.js
+      inputs:
+        member: {}
+  sequences:
+    fellowship_membership:
+      actions: member_join, member_process, member_equip
+```
+
+#### ```member_join.js``` code snippet:
+```javascript
+function main(params) {
+
+    var member = {name:"", place:"", region:"", occupation:"", joined:"", organization:"",
item:"" };
+
+    // The organization being joined is fixed
+    member.organization = "fellowship";
+
+    // Fill in a member record from parameters
+    member.name = params.name;
+    member.place = params.place;
+    member.occupation = params.job;
+
+    // Save the current timestamp when we created the member record
+    member.joined = Date.now();
+
+    return { member: member };
+}
+```
+
+#### ```member_process.js``` code snippet:
+```javascript
+const regionMap = new Map([
+    ['Hobbiton', 'Eriador'],
+    ['Rivendell', 'Eriador'],
+    ['Minas Tirith', 'Gondor'],
+    ['Lake Town', 'Rhovanion'],
+    ['Minas Morgul', 'Mordor'],
+]);
+
+function main(params) {
 
+    // Augment the member (record) created in the previous Action
+    member = params.member;
+    member.region = regionMap.get(member.place) || "unknown";
+    member.date = new Date(member.joined).toLocaleDateString();
+    member.time = new Date(member.joined).toLocaleTimeString();
+
+    return { member: member };
+}
 ```
 
+#### ```member_equip.js``` code snippet:
+```javascript
+const equipmentMap = new Map([
+    ['gentleman', 'ring'],
+    ['wizard', 'staff'],
+    ['archer', 'bow'],
+    ['knight', 'sword'],
+]);
+
+function main(params) {
+
+    // Equip the member based upon their occupation
+    member = params.member;
+    member.item = equipmentMap.get(member.occupation) || "None";
+
+    return { member: member };
+}
+
+
 ### Deploying
 ```sh
-$ wskdeploy -m
+$ wskdeploy -m docs/examples/manifest_sequence_basic.yaml
 ```
 
 ### Invoking
 ```sh
-$ wsk action invoke
+$ wsk action invoke fellowship_package/fellowship_membership -p name frodo -p place Hobbiton
-p job gentleman  -b
 ```
 
 ### Result
-The invocation should return an 'ok' with a response that includes this result:
+The invocation should return a 'success' response that includes this result:
 ```json
+"result": {
+    "member": {
+        "joined": 1507155846307,
+        "name": "frodo",
+        "occupation": "gentleman",
+        "organization": "fellowship",
+        "place": "Hobbiton",
+        "region": "Eriador",
+        "date": "10/4/2017",
+        "time": "10:24:06 PM",
+        "item": "ring"
+    }
+}
+```
 
+and with three log entries (one for each Action in the sequence):
+```json
+"logs": [
+    "4fdb1f27c6c84ca09b1f27c6c83ca0c6",
+    "038567b035b743018567b035b70301c9",
+    "aa730c99319f4b8bb30c99319f9b8b3b"
+]
 ```
 
 ### Discussion
--
+
+we can inspect the logs from the first Action "```member_join```" to view its input parameters
"```params```" which where passed on the command line invocation:
+```sh
+$ wsk activation logs 4fdb1f27c6c84ca09b1f27c6c83ca0c6
+params: {
+    "name": "frodo",
+    "place": "Hobbiton",
+    "job": "gentleman"
+ }
+```
+the input paramaters are augmented by the first Action in the sequence to produce the output
"member" object:
+
+```json
+member: {
+    "organization": "fellowship",
+    "name": "frodo",
+    "place": "Hobbiton",
+    "region": "",
+    "occupation": "gentleman",
+    "joined": 1507155846307,  // Date() in msec.
+    "item": ""
+}
+
+```
+
+the second Action in the sequence further processes and adds to the "```member```" data:
+```sh
+$ wsk activation logs 038567b035b743018567b035b70301c9
+
+```
+
+```json
+member: {
+    "organization": "fellowship",
+    "name": "frodo",
+    "region": "Eriador",
+    "place": "Hobbiton",
+    "occupation": "gentleman",
+    "joined": 1507155846307,
+    "date": "10/4/2017",
+    "time": "10:24:06 PM",
+    "item": ""
+}
+```
+
+Finally, the last Action in the sequence adds the "```item```" value to the "```member```"
data to produce the completed record:
+```sh
+$ wsk activation logs aa730c99319f4b8bb30c99319f9b8b3b
+
+```
+
+```json
+member: {
+    "organization": "fellowship",
+    "name": "frodo",
+    "region": "Eriador",
+    "place": "Hobbiton",
+    "occupation": "gentleman",
+    "joined": 1507155846307,
+    "date": "10/4/2017",
+    "time": "10:24:06 PM",
+    "item": "ring"
+}
+```
 
 ### Source code
-The manifest file for this example can be found here:
--
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_hello_world.yaml](examples/manifest_sequence_basic.yaml)
+- [member_join.js](examples/src/member_join.js)
+- [member_process.js](examples/src/member_process.js)
+- [member_equip.js](examples/src/member_equip.js)
 
 ### Specification
 For convenience, the Actions and Parameters grammar can be found here:
@@ -50,9 +236,9 @@ For convenience, the Actions and Parameters grammar can be found here:
 <div align="center">
 <table align="center">
   <tr>
-    <td><a href="">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="wskdeploy_action_env_var_parms.md#actions">&lt;&lt;&nbsp;previous</a></td>
     <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
-    <td><a href="">next&nbsp;&gt;&gt;</a></td>
+    <td><a href="wskdeploy_triggerrule_basic.md#triggers-and-rules">next&nbsp;&gt;&gt;</a></td>
   </tr>
 </table>
 </div>
diff --git a/docs/wskdeploy_triggerrule_basic.md b/docs/wskdeploy_triggerrule_basic.md
index 9faee55..9890b6b 100644
--- a/docs/wskdeploy_triggerrule_basic.md
+++ b/docs/wskdeploy_triggerrule_basic.md
@@ -113,7 +113,7 @@ For convenience, the Actions and Parameters grammar can be found here:
 <div align="center">
 <table align="center">
   <tr>
-    <td><a href="wskdeploy_action_env_var_parms.md#actions">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="wskdeploy_sequence_basic.md#sequences">&lt;&lt;&nbsp;previous</a></td>
     <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
     <td><a href="wskdeploy_triggerrule_trigger_bindings.md#triggers-and-rules">next&nbsp;&gt;&gt;</a></td>
   </tr>
diff --git a/tests/dat/actions/dump_params.js b/tests/dat/actions/dump_params.js
index 651427a..c7179d1 100644
--- a/tests/dat/actions/dump_params.js
+++ b/tests/dat/actions/dump_params.js
@@ -2,5 +2,7 @@
 // license agreements; and to You under the Apache License, Version 2.0.
 
 function main(params) {
-  return {payload:  params};
+  parms = "params: " + JSON.stringify(params, null, 4);
+  console.log(parms);
+  return {payload:  parms};
 }

-- 
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <commits@openwhisk.apache.org>'].

Mime
View raw message