1 | # Overview
|
2 |
|
3 | The purpose of the emote tool is to create projects that contain Emotive applications and deploy them to the Emotive
|
4 | cloud service. The emote project consists of the files that reside on your local file system. The Emotive cloud service
|
5 | does not keep track of your project. When you deploy a project, the contents the the project, such as apps and
|
6 | integration proxies, are uploaded to the Emotive cloud service.
|
7 |
|
8 | ## Installing emote
|
9 |
|
10 | emote is implemented in node.js, which must be installed prior to installing emote. See [here](http://nodejs.org/download/)
|
11 | for installation instructions. emote requires node.js v0.8.3 or higher.
|
12 |
|
13 | IMPORTANT: before proceeding to install emote, run this simple test to verify your node.js and node package manager install:
|
14 |
|
15 | $ npm install request
|
16 |
|
17 | This installs the "request" package, and it insures that npm is configured correctly. Don't skip this step
|
18 | unless you are already using node in your development system. [If the very first install using npm uses the '-g' option (see below) it triggers a bug in npm that will make later installs difficult.]
|
19 |
|
20 | emote is then installed using npm, the node package manager. If you install with the '-g' option, emote will be in your path and available from the command line.
|
21 |
|
22 | On a PC:
|
23 |
|
24 | $ npm install -g emote
|
25 |
|
26 | On a OS-X or Linux system:
|
27 |
|
28 | $ sudo npm install -g emote
|
29 |
|
30 | ## Example project
|
31 |
|
32 | Here is an example of creating a project. The commands used are described in more detail below.
|
33 |
|
34 | $ emote create myproj
|
35 | Created empty project myproj
|
36 | $ cd myproj
|
37 | $ ls
|
38 | app model project.json proxy
|
39 | $
|
40 |
|
41 | emote creates a project directory that contain a project.json file and a subdirectory for app, model, and proxy code.
|
42 |
|
43 | Project specific settings are stored in project.json. This file is also used to identify the root of a project. If you
|
44 | are in a project subdirectory and issue an emote command it finds the root of the project by going up the directory
|
45 | structure until project.json is found.
|
46 |
|
47 | ### Listing available a sample applications
|
48 |
|
49 | There are a number of sample applications available from the emotive mms. Use the "list" command to see their names:
|
50 |
|
51 | $ emote list sample -g
|
52 | Connecting to MMS as user mark@emotive.com at https://test.mms.emotive.com
|
53 |
|
54 | targetType name lastModifiedAt
|
55 | ----------- ----------------------- --------------------
|
56 | CdmResource sample-AppList 2013-01-30T20:43:35Z
|
57 | CdmResource sample-AppListjQueryUI 2013-01-30T20:43:35Z
|
58 | CdmResource sample-AppListNeutral 2013-01-30T20:43:35Z
|
59 | CdmResource sample-AppListTablet 2013-01-30T20:43:36Z
|
60 | CdmResource sample-BarCode 2013-01-30T20:43:36Z
|
61 | CdmResource sample-Camera 2013-01-30T20:43:36Z
|
62 | CdmResource sample-GoogleMaps 2013-01-30T20:43:36Z
|
63 | CdmResource sample-GPS 2013-01-30T20:43:36Z
|
64 | CdmResource sample-HelloWorld 2013-01-30T20:43:36Z
|
65 | CdmResource sample-Messaging 2013-01-30T20:43:36Z
|
66 | CdmResource sample-Pagination 2013-01-30T20:43:36Z
|
67 | CdmResource sample-PerfTest 2013-01-30T20:43:37Z
|
68 | CdmResource sample-SalesforceLeads 2013-01-30T20:43:37Z
|
69 | CdmResource sample-SignatureCapture 2013-01-30T20:43:37Z
|
70 | CdmResource sample-SplitView 2013-01-30T20:43:37Z
|
71 | CdmResource sample-USGS 2013-01-30T20:43:37Z
|
72 | CdmResource sample-Weblet 2013-01-30T20:43:37Z
|
73 | CdmResource sample-WhereAmI 2013-01-30T20:43:37Z
|
74 | 18 rows.
|
75 | $
|
76 |
|
77 | ### Downloading a sample application into your project
|
78 |
|
79 | Use the download command to bring a copy of a sample application into your project:
|
80 |
|
81 | $ emote download sample sample-USGS
|
82 | Connecting to MMS as user mark@emotive.com at https://test.mms.emotive.com
|
83 | Finished downloading sample: sample-USGS
|
84 | $ ls */USGS
|
85 | app/USGS:
|
86 | icon114.png icon48.png icon72.png source.js
|
87 | icon144.png icon57.png source.html source.properties
|
88 |
|
89 | model/USGS:
|
90 | model.json
|
91 |
|
92 | proxy/USGS:
|
93 | README.md index.js package.json
|
94 | $
|
95 |
|
96 | The download commands copies an app, model, and proxy for the USGS Earthquake Package into your project.
|
97 |
|
98 | The download command can also be used to create sample instances of CDM types into your project. For instance, after downloading and deploying the sample-USGS application, which defines a type called Feature,
|
99 |
|
100 | $ emote download type Feature
|
101 | Connecting to MMS as user mark@emotive.com at https://test.mms.emotive.com
|
102 | Finished downloading type Feature
|
103 |
|
104 | will write a sample instance of the type Feature to the file types/Feature.json .
|
105 |
|
106 | ### Credentials and the profile.json file
|
107 |
|
108 | After creating your project, additional emote commands, like list, often require communicating with the Emotive cloud service (MMS). This requires credentials, including the username and password you were provided when signing up to use the Emotive cloud service. The default profile.json created in your project causes emote to prompt for server, username, and password:
|
109 |
|
110 | $ cat profile.json
|
111 | {
|
112 | "server": "<<Emotive server URL>>https://dev.emotive.com",
|
113 | "username": "<<Emotive username>>",
|
114 | "password": "<<Emotive password>>"
|
115 | }$
|
116 |
|
117 | The << >> notation indicate that the system should prompt. Any value after the << >> is a default value. You can replace the values in this file with your credentials if you want to avoid typing them on each invocation of emote. E.g.
|
118 |
|
119 | $ cat profile.json
|
120 | {
|
121 | "server": "https://dev.emotive.com",
|
122 | "username": "me@mydomain.net",
|
123 | "password": "<<Emotive password>>"
|
124 | }$
|
125 |
|
126 | With this profile.json, it will only prompt for the password, which saves some typing. You could also put your cleartext password in the profile.json if you plan on keeping the file in a secure location.
|
127 |
|
128 | ### Deploying your project to the emotive MMS
|
129 |
|
130 | The deploy command uploads your app, model, and proxy code to MMS.
|
131 |
|
132 | $ emote deploy
|
133 | Connecting to MMS as user mark@emotive.com at https://dev.emotive.com
|
134 | npm http GET https://registry.npmjs.org/emproxy
|
135 | npm http GET https://registry.npmjs.org/request
|
136 | npm http 200 https://registry.npmjs.org/emproxy
|
137 | npm http 200 https://registry.npmjs.org/request
|
138 | npm http GET https://registry.npmjs.org/emutils
|
139 | npm http GET https://registry.npmjs.org/portfinder/0.2.1
|
140 | npm http 200 https://registry.npmjs.org/portfinder/0.2.1
|
141 | npm http GET https://registry.npmjs.org/portfinder/-/portfinder-0.2.1.tgz
|
142 | npm http 200 https://registry.npmjs.org/emutils
|
143 | npm http GET https://registry.npmjs.org/emutils/-/emutils-1.0.8.tgz
|
144 | npm http 200 https://registry.npmjs.org/portfinder/-/portfinder-0.2.1.tgz
|
145 | npm http 200 https://registry.npmjs.org/emutils/-/emutils-1.0.8.tgz
|
146 | npm http GET https://registry.npmjs.org/mkdirp
|
147 | npm http 200 https://registry.npmjs.org/mkdirp
|
148 | USGS@1.0.0 node_modules/USGS
|
149 | ├── request@2.9.203
|
150 | └── emproxy@1.0.9 (emutils@1.0.8, portfinder@0.2.1)
|
151 | Exec'ing query file: model.json
|
152 | CREATED CdmExternalSystem: USGS
|
153 | Inserted CdmTypeBinding: Feature
|
154 | Completed binding of CDM type: Feature
|
155 | Finished executing directives.
|
156 | Deployed model USGS
|
157 | Uploading resource: USGS of length 122632
|
158 | Deployed proxy USGS
|
159 | Uploading app: USGS of length 65418
|
160 | App USGS added
|
161 | Deployed app USGS
|
162 | $
|
163 |
|
164 | Note from the example output that deploy has several intermediate steps. First it does a "build" to make sure that the proxies have been installed using npm. The npm install will cause any dependencies to be pull into the staging area. After that, it deploys the model, the proxy, and the app for the USGS sample by uploading them to http://dev.emotive.com.
|
165 |
|
166 | After running emote deploy, you will be able to run the app and view the USGS earthquake data on your mobile device (i.e. iPhone, Android tablet, etc.)
|
167 |
|
168 | ### Adding modules
|
169 |
|
170 | The "add" command adds additional content to your project. "modules" are created under the app, model, and/or proxy directories. When a "template" is specified for the module being added, emote copies initial code into the module directory. For example, the following command adds a proxy to "myproj":
|
171 |
|
172 | $ emote add proxy myprox1 --template Salesforce
|
173 | Adding proxy from template Salesforce
|
174 | $ ls proxy
|
175 | myprox1
|
176 | $ ls proxy/myprox1
|
177 | README.md index.js package.json
|
178 | $
|
179 |
|
180 | In this example, a new proxy, "myprox1" has been added the used the Salesforce template. A proxy that allows easy integration of your app with Salesforce has been included. The Saleforce proxy is a Node.js module. The package.json file contains the parameters needed to deploy this proxy using npm.
|
181 |
|
182 | In an emote project, modules work to provide the functionality needed by your emotive application. The module name for a proxy and for a model correspond to the "externalSystem" name of your emotive application. In the next example, we add a "model" module to work with our proxy:
|
183 |
|
184 | $ emote add model myprox1 --template Salesforce
|
185 | Adding model from template Salesforce
|
186 | $ ls model/
|
187 | myprox1
|
188 | $ ls model/myprox1/
|
189 | salesforce.json
|
190 | $
|
191 |
|
192 | The Salesforce template for the model creates a "salesforce.json" file that contains metadata that specifies what Salesforce object you would like to integrate into your appication, and how they correspond with the emotive CDM (common data model.)
|
193 |
|
194 | # Commands
|
195 |
|
196 | ## Common Parameters
|
197 |
|
198 | ## module types
|
199 |
|
200 | Several commands include a module type (or group of module types) as
|
201 | one of their parameters. Module types include:
|
202 |
|
203 | * app
|
204 | * model
|
205 | * operation
|
206 | * proxy
|
207 | * test
|
208 | * theme
|
209 |
|
210 | A module type is a directory that is a child of the Emote project directory.
|
211 |
|
212 | A module type parameter can be:
|
213 |
|
214 | 1. A single type e.g. __app__ or __model__
|
215 | 2. A group of module types joined by __+__, e.g. __app+theme__ or
|
216 | __proxy+test+operation__
|
217 | 3. __all__, meaning all module types
|
218 |
|
219 | ## module names
|
220 |
|
221 | A module name is the name of a directory that is a child of a module type directory. For models and proxies, this will be the same as the "externalSystem" name in the CDM.
|
222 |
|
223 | ## Commands
|
224 |
|
225 | ### emote default action
|
226 |
|
227 | With no parameters or options, emote provide basic information on the context in which it is running. E.g.
|
228 |
|
229 | $ emote
|
230 | version 2.2.0
|
231 | profile /Users/mark/profile.json
|
232 | username mark@emotive.com on https://dev.emotive.com
|
233 | project myproj
|
234 | $
|
235 |
|
236 | The following options can only be used when emote is passed no other parameters:
|
237 |
|
238 | * --help : show a summary of the available commands and options
|
239 | * --info : default, the same as 'emote' with no options, as above.
|
240 | * --readme : outputs this README.md file to the console
|
241 | * --emoteDir : prints the directory in which the emote source code is deployed
|
242 | * --version : prints the version on emote
|
243 | * --whoami : prints the current username for emote
|
244 | * --doc : prints the URL to doc.emotive.com
|
245 |
|
246 | ### add
|
247 |
|
248 | `emote add [`_moduleType_ `[`_moduleName_`]] [--template` _templateName_]
|
249 |
|
250 | _moduleType_ is a standard module type parameter (see above).
|
251 |
|
252 | _moduleName_ is a standard module name parameter.
|
253 |
|
254 | __--template__ is optional. If it is included, the specifid parts from the named template (e.g. Salesforce) will be included in the project using the specified module name (which defaults to __default__).
|
255 |
|
256 | If __--template__ is omitted, _moduleType_ and _moduleName_ are required, and an empty directory _ProjectRoot/moduleType/moduleName_ is created.
|
257 |
|
258 | ### create
|
259 |
|
260 | `emote create` _projectName_
|
261 |
|
262 | Create a new Emotive project in the current directory. _projectName_ is the name of the directory created. Subdirectories __model__, __app__, __proxy__ are created.
|
263 |
|
264 | profile.json is created with default values that cause emote to prompt for credentials. (See profile.json above.)
|
265 |
|
266 | ### download
|
267 |
|
268 | `emote download` (app | sample) _identifier_
|
269 |
|
270 | This command will download a previously deployed artifact from the MMS cloud service and save as files in your project
|
271 | directory. Currently, this is only implemented for apps and samples.
|
272 |
|
273 | For apps, the command is:
|
274 |
|
275 | `emote download app` _appId_
|
276 |
|
277 | Example:
|
278 |
|
279 | emote download app usgs
|
280 |
|
281 | will download the app with ID "usgs" from your tentant and add it to your current project. Note that your current project is found using on your current directory.
|
282 |
|
283 | For samples, the command is:
|
284 |
|
285 | `emote download sample` _sampleName_
|
286 |
|
287 | Where the list of sample names can be obtained by using:
|
288 |
|
289 | emote list sample -g
|
290 |
|
291 |
|
292 | ### deploy
|
293 |
|
294 | `emote deploy [`_moduleType_ `[` _moduleName_ `]]`
|
295 |
|
296 | _moduleType_ is a standard module type parameter.
|
297 |
|
298 | _moduleName_ is a standard module name parameter.
|
299 |
|
300 | The __deploy__ command works within any subdirectory of a project. With no parameters, __deploy__ will deploy the entire project. If parmeters are present, they specify which parts of the project to deploy.
|
301 |
|
302 | Example:
|
303 |
|
304 | emote deploy proxy usgs
|
305 |
|
306 | Will deploy the "usgs" proxy that was generated into your project.
|
307 |
|
308 | Note that until a project has been deployed, the MMS cloud service (at mms.emotive.com) has no knowledge of the project.
|
309 | By deploying the generated project, the app is made available to users.
|
310 |
|
311 | ### undeploy
|
312 |
|
313 | `emote deploy [`_moduleType_ `[` _moduleName_ `]]`
|
314 |
|
315 | _moduleType_ is a standard module type parameter.
|
316 |
|
317 | _moduleName_ is a standard module name parameter.
|
318 |
|
319 | This removes objects that have been deployed. E.g.
|
320 |
|
321 | emote undeploy app usgs
|
322 |
|
323 | Removes the app named __usgs__.
|
324 |
|
325 | Undeploy is currently implemented only for app, model, and theme.
|
326 |
|
327 | Undeploying a model, e.g.
|
328 |
|
329 | emote undeploy model
|
330 |
|
331 | removes the CdmExternalSystem definitions for the tenant and all bindings to those external systems. It does not remove any CdmType's that were part of the model, but those types will no longer be bound to an external system.
|
332 |
|
333 | emote undeploy theme custom
|
334 |
|
335 | This will undeploy the theme named __custom__ (the theme name defaults to "default" if none is specified).
|
336 |
|
337 | ### build ###
|
338 |
|
339 | `emote build [`_moduleType_ `[` _moduleName_ `]]`
|
340 |
|
341 | This does whatever is necessary to build the project before deploying it. By default, it builds the entire project. If _moduleType_ and/or _moduleName_ are specified, only that part of the project is built.
|
342 |
|
343 | It is not necessary to buiuld a project before deploying it; the __deploy__ comand builds the project automatically.
|
344 |
|
345 | ### list
|
346 |
|
347 | `emote list` _artifactType_ _artifactName_ `[-g]`
|
348 |
|
349 | The __-g__ option indicates that "global" objects, those that were created by the system rahter than the current tenant, should also be listed.
|
350 |
|
351 | _artifactType_ is one of:
|
352 |
|
353 | * app : list deployed applications,
|
354 | * model : list defined CdmType's
|
355 | * proxy : list the resource for a deployed proxy
|
356 | * sample : list the resource for deployed sample projects
|
357 | * resource : list all resources
|
358 | * template : list template available in emote (see 'add' command)
|
359 | * externalSystem : list CdmExternalSystem objects
|
360 |
|
361 | _artifactName_ can be wildcarded using leading, trailing, or embedded '*' characters. When wildcards are used, the artifact name should be quoted. E.g.
|
362 |
|
363 | emote list app 'A*'
|
364 |
|
365 | Will list all the apps where the name starts with 'A'.
|
366 |
|
367 | emote list resource '*cdf*' -g
|
368 |
|
369 | Lists all the resources that contain 'cdf' in their name. Global resources included.
|
370 |
|
371 |
|
372 | ### log
|
373 |
|
374 | `emote log` _startTime_ _endTime_ `[--tail] [--local] [--csv]`
|
375 |
|
376 | This displays the log file for your proxy running on the MMS server. __startTime__ indicates the stamp of the earliest message to show. It can be specified in several formats.
|
377 |
|
378 | * GMT specified as ISO 8601: `2012-09-13T17:30:00`
|
379 | * Local time specified as ISO 8601 and including the offset to the timezone: `2012-09-13T10:30:00-07:00`
|
380 | * Local time, assuming your current timezone (the quotes are required): `"2012-09-13 10:30:00"`
|
381 | * Relative time (as in, "starting 5 minutes ago"): `5m`
|
382 | * Relative time (as in, "starting 2 hours ago"): `2h`
|
383 |
|
384 | If you specify just __startTime__ you will get all the log entries that have been recorded since that time until the current moment. If you specify __endTime__ as well, you will only see those records between __startTime__ and __endTime__.
|
385 |
|
386 | You can add the __--tail__ option which will show all the records from the__startTime__ to the present, and then
|
387 | periodically append new log records as they arrive. (If you specify __--tail__ with no __startTime__ it will assume you wanted a __startTime__ of __5m__.)
|
388 |
|
389 | The output is normally shown with GMT timestamps, but if you add the __--local__ option the timestamps will be converted
|
390 | to your local time zone (and the times will have an "L" appended to remind you it's not GMT).
|
391 |
|
392 | The output is normally designed to be human-readable, but you can specify the __--csv__ option and the output will be
|
393 | written in CSV format so it could be fed into another program.
|
394 |
|
395 | Some common examples:
|
396 |
|
397 | Show the log data for the previous 5 minutes then tail the log to show new output as it arrives:
|
398 |
|
399 | emote log --tail
|
400 |
|
401 | Show the log data for the previous 2 minutes then tail the log to show new output as it arrives, converting the timestamps to local time:
|
402 |
|
403 | emote log 2m --tail --local
|
404 |
|
405 | Show the log data for a certain date from 9 to 10 am in the local time zone, output in CSV format:
|
406 |
|
407 | emote log "2012-09-13 09:00:00" "2012-09-13 10:00:00" --csv
|
408 |
|
409 |
|
410 | ### exec
|
411 |
|
412 | `emote exec` _commandFile_`.json`
|
413 |
|
414 | This takes a parameter which is the name of a file containing JSON for an Array of MMS REST requests. It submits the
|
415 | requests to MMS as a synchronously run series of commands, and logs the REST responses to stdout.
|
416 |
|
417 | Example:
|
418 |
|
419 | emote exec myfile.json
|
420 |
|
421 | Where myfile.json contains:
|
422 |
|
423 | {"op":"SELECT", "targetType":"CdmExternalSystem"}
|
424 |
|
425 | Will select a list of the External Systems for your tenant which are registered with MMS and print it to stdout.
|
426 |
|
427 | ### getWsdl
|
428 |
|
429 | `emote getWsdl` _moduleName_ _wsdlUrl_ _service_ _port_ [_username_ _password_]
|
430 |
|
431 | This creates several files in several different module types, all in the module _moduleName_.
|
432 |
|
433 | _moduleName_ is a standard module name.
|
434 |
|
435 | _wsdlUrl_, _service_, _port_, specifies a WSDL port which the module will comminicate with. The service and port are specified by their unqualified names.
|
436 |
|
437 | This is the first step in creating a SOAP-service-based subproject. It will fetch the WSDL for a web service and create three
|
438 | files in your project's <subproject>/model directory:
|
439 |
|
440 | * wsdl.json contains a JSON version of the web service's definitions.
|
441 | * wsdlOps.json contains a list of the web service's operations.
|
442 | * proxyConfig.json allows you to configure the connection from the generated proxy to toe target SOAP service.
|
443 |
|
444 | wsdlOps.json determined which web service operations will be part of the generated subproject. Originally, all of the
|
445 | operations are disabled (set to false.) Before generating, edit this file to set the desired operations to "true".
|
446 |
|
447 | proxyConfig.json will optionally pass these connection properties to the generated proxy. (By default, all are set to null,
|
448 | so the default behavior applies.)
|
449 |
|
450 | * By default, the proxy will expect to find the SOAP service at the soapAddress given in the WSDL port. If this is
|
451 | incorrect, set the soapAddress property in proxyConfig.json to the correct service endpoint URL.
|
452 | * By default, no HTTP[S] authentication is used when talking to the SOAP service. If basic authentication is required,
|
453 | set the user name and password in proxyConfig.json.
|
454 |
|
455 | After editing these two files, use the generateFromWsdl command to generate your subproject.
|
456 |
|
457 | ### generateFromWsdl
|
458 |
|
459 | `emote generateFromWsdl` _moduleName_
|
460 |
|
461 | This will generate a SOAP-service-based subproject. Before running this, you must use the getWsdl command to load WSDL-based definitions into your module.
|
462 |
|
463 | ### status
|
464 |
|
465 | `emote status`
|
466 |
|
467 | Check the availability of the Emote server.
|
468 |
|
469 | ### test
|
470 |
|
471 | `emote test` [_moduleName_]
|
472 |
|
473 | Run the Javascript tests in the test directory of the current project. If _moduleName_ is specified, run only the test in that subdirectory.
|
474 |
|
475 | # Credentials
|
476 |
|
477 | Here are the methods of supplying MMS credential to emote.
|
478 |
|
479 | ## .emote\_profile
|
480 |
|
481 | MMS credentials can be using a ".emote\_profile" file, which can be located in the user directory. This is a JSON file. Example:
|
482 |
|
483 | {
|
484 | "username":"myuser",
|
485 | "password":"mypassword",
|
486 | "server":"https://mms.emotive.com"
|
487 | }
|
488 |
|
489 | ## profile.json in project
|
490 |
|
491 | If the file "profile.json" is present in the root of a project, it is used for commands within that project. It has
|
492 | the same format as .emote\_profile
|
493 |
|
494 | ## Profile file supplied on command line
|
495 |
|
496 | The profile file name can also be included as a command line argument:
|
497 |
|
498 | emote --profile alt\_profile.json <command> ...
|
499 |
|
500 | ## Credentials on command line
|
501 |
|
502 | A username and password (and optionally a server URL) can be supplied on the command line:
|
503 |
|
504 | --password, -p Emotive password
|
505 | --username, -u Emotive username
|
506 | --server, -s Emotive server URL [default: "http://mms.emotive.com"]
|
507 |
|
508 | ## Precedence
|
509 |
|
510 | Starting with the lowest precedence, each source of credential described above overrides the ones before it. So the precedence is:
|
511 |
|
512 | 1. Username and password as command line parameters
|
513 | 2. Profile file on command line
|
514 | 3. "profile.json" in project
|
515 | 4. .emote\_profile
|
516 |
|
517 | Individual values are overridden, so "username" may be taken from one profile, while "server" is defined in another. Properties in "externalCredentials" are merged by name.
|