Merge pull request #11 from radumg/documentation

Documentation

CONTRIBUTING.md

@@ -1,81 +1,12 @@
 # Contributing
 
-When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. 
+When contributing to this repository, before making a change please first discuss the change you wish to make with the owners of this repository. You can do this by [creating an issue](http://www.github.com/radumg/DynAsana/issues/new)
 
-Please note we have a code of conduct, please follow it in all your interactions with the project.
+Please note we also have a [CODE OF CONDUCT](https://github.com/radumg/DynAsana/CODE_OF_CONDUCT.md), so please read & follow it in all your interactions with the project.
 
 ## Pull Request Process
 
 1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
-2. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
-3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
-4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the reviewer to merge it for you.
-
-## Code of Conduct
-
-### Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-### Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-### Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-### Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
-
-### Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-### Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+2. Update the `README.md` with details of changes to the integration, this includes new environment variables, exposed ports, useful file locations and container parameters.
+3. Increase the version numbers in any examples files and the `README.md` to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
+4. You may merge the Pull Request in once you have the sign-off of two other developers/the repository owner, or if you do not have permission to do that, you may request the reviewer to merge it for you.

Dynamo package/DynAsana/pkg.json

@@ -2,8 +2,10 @@
 "license": "AGPL-3.0",
 "file_hash": null,
 "name": "DynAsana",
-"version": "2017.1.1.0",
-"description": "Asana Integration for Dynamo",
+"version": "1.2.0",
+"description": "DynAsana is a Dynamo package providing integration with task management app Asana, allowing you to retrieve & create tasks. Currently includes support for retrieving most Asana objects (such as Tasks, Projects, Users, Tags) and creating Tasks, Projects & Tags. Future updates will enable modification & deletion of existing items & support for OAuth flow.
+
+	This is an open-source package, please visit repository ( https://github.com/radumg/DynAsana ) to submit improvement requests, bug reports or to contribute. Alternatively, tweet at me @radugidei .",
 "group": "radugidei",
 "keywords": [
 "Asana",

README.md

@@ -12,6 +12,8 @@ Includes GET (retrieval) support for :
 
 Includes POST (creation) support for :
 - tasks
+- projects
+- tags
 
 Soon to include support for :
 - OAuth flow
@@ -26,71 +28,119 @@ A new category called `DynAsana` should appear in the Dynamo node library, but i
 
 # Using DynAsana
 
-DynAsana currently exposes a few nodes in Dynamo, in the `DynAsana` category, organised in a further 2 sub-categories :
+DynAsana currently exposes a few nodes in Dynamo, in the `DynAsana` category and further organised into classes that reflect Asana objects.
+There are a few exceptions, namely :
 * Client
-* Classes
 * Authentication
+* Helpers
+
+These 3 classes are part of the integration and do not represent actual Asana objects.
+
+![dynasana](https://user-images.githubusercontent.com/11439624/27520915-36358b86-5a0d-11e7-9a1a-f34b370bc8d6.PNG)
+
+
+## Class structure
+As mentioned, each class represents an Asana object, for example `Tags`.
+
+This structure allows the creation of Asana objects which are used to interact with the web service as well as for easy & direct use in Dynamo. They follow the standard Dynamo convention of having nodes for 
+- creating new objects `(+)`
+- performing actions `(bolt)`
+- querying `(?)`
+
+![Structure](https://user-images.githubusercontent.com/11439624/27520902-073c9fcc-5a0d-11e7-88e8-83e032f91ef1.PNG)
+
+### Create an object
+To create a tag for example, use nodes in the `+` section.
+Using Tag as an example, you'll find 3 nodes :
+
+**Tag()**
+```
+Use this node to create an empty Tag object. Every class has this empty constructor that allows you to create offline objects - meaning they're never sent to the Asana servers.
+```
+
+**CreateTag**
+```
+Use this node to create a Tag object on the Asana server.
+
+This node requires you to build an offline tag first, then supplying that (along with a client) to this node as input. The result will be the newly-created Tag, as returned by the Asana servers.
+Most classes behave this way.
+```
+
+### Perform actions & modify objects
+To perform actions and/or communicate with the Asana servers, use the nodes in modify section (lightning bolt).
+
+**GetAllTags**
+```
+Use this node to retrieve all Tags in your workspace from the Asana servers, returning complete Tag objects which can then be used for modification, assigning to a task, etc. 
+Any nodes that include web action verbs such as Get, Post, Put, Delete, involve communicating with the Asana servers.
+```
 
-## Simple examples
+### Query nodes
+The query nodes, marked with `?` in Dynamo allow you to see the properties of an object. Use these for troubleshooting and debugging.
+
+
+## Example Dynamo graphs
+### Simple examples
 The `samples` folder includes a few simple examples that show you how to :
 - retrieve a single task
-- retrieve a project
 - retrieve tasks in a project
-- create a new task in a project
+- retrieve all projects
 
 Retrieve a single task :
-![samples-simplepostmessage](https://cloud.githubusercontent.com/assets/)
-
-Retrieve a single project :
-![samples-simplepostmessage](https://cloud.githubusercontent.com/assets/)
+![samples-simplepostmessage](https://raw.githubusercontent.com/radumg/DynAsana/documentation/Samples/Samples-Simple-GetTaskById.png)
 
-## More complex example
-The `samples` folder also includes more complex examples. The reason these are considered more complex examples is because execution is cascaded, requiring multiple GET and/or multiple POST operations to achieve.
+Retrieve projects :
+![samples-simplepostmessage](https://raw.githubusercontent.com/radumg/DynAsana/documentation/Samples/Samples-Simple-GetProjects.png)
 
 #### Retrieve tasks in a project
 First retrieves projects from a workspace, then retrieves tasks in that specific project.
-![samples-simplepostmessage](https://cloud.githubusercontent.com/assets/11439624/23580567/2a0a5fea-00fc-11e7-82d1-5450e6ab1a2a.png)
+![samples-simplepostmessage](https://raw.githubusercontent.com/radumg/DynAsana/documentation/Samples/Samples-Simple-GetTasksByProject.png)
+
+With all the samples, please remember to fill in your own API key, the one used in the samples is invalid or has been deactivated.
+
+### Complex examples
+The `samples` folder also includes more complex examples. The reason these are considered more complex examples is because execution is cascaded, requiring multiple GET and/or multiple POST operations to achieve.
+
+Included complex samples :
+- create a new task in a project
 
 #### Create a new task in a workspace
-First retrieves a workspace, then creates a new task in that specific workspace.
-![samples-simplepostmessage](https://cloud.githubusercontent.com/assets/)
+First retrieves a workspace & project, then creates a new task in that specific workspace/project pair.
+![samples-simplepostmessage](https://raw.githubusercontent.com/radumg/DynAsana/documentation/Samples/Samples-Complex-CreateTask.png)
 
-With all the samples, please remember to fill in your own API key, the one used in the samples has been deactivated.
+## Nodes
 
-## Client
-This subcategory implements a client for access to the Asana API.
+### Client
+This class implements a client for access to the Asana API.
+Think of a client as an individual connection to the Asana servers that all actions require.
 
-![client](https://cloud.githubusercontent.com/assets/)
+In this integration, clients are not static, allowing you to use multiple clients in the same graph, to create tasks in different organisations, etc. 
 
-Please note each client requires a valid API key and the integration does not currently support OAuth, although this is planned for a future update. See the [Authentication]() section for details on setting the API key up.
+Please note each client requires a valid API key and the integration does not currently support OAuth, although this is planned for a future update. See the **Authentication** section for details on setting the API key up.
 
-### Client node
+#### Client node
 This node creates a new Asana client. It takes in only 1 input :
 ```
 1. token - an OAuth token.
 ```
 
-### Query nodes
-The query nodes, marked with `?` in Dynamo allow you to see the properties of a Client. Use these for troubleshooting and debugging.
-
-## Classes
-This subcategory allows the creation of Asana objects which are used to interact with the web service as well as for easy & direct use in Dynamo. They follow the standard Dynamo convention of having nodes for 
-- creating new objects (+)
-- performing actions (bolt)
-- querying (?)
-
-![classes](https://cloud.githubusercontent.com/assets/)
-
-## Authentication
+### Authentication
 
-This repository reads the Asana API key directly from an XML file called `keys.xml`. You'll notice this file is not provided in the repository, so you'll have to create your own from the sample one that is provided.
+This integration reads the Asana API key directly from an XML file called `keys.xml`. You'll notice this file is not provided in the repository, so you'll have to create your own from the sample one that is provided.
 1. Copy `keys.sample.xml` to `keys.xml`
 2. Replace the token with your Asana one.
 
 The token is the text between `<token>` and `</token>` and looks something like this : `Bearer 0/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`, where the `x` are a long string of alphanumeric characters. These `xxxx` characters represent the actual API key, see below how to obtain one.
 
 *Note* : to create a new API key, please visit the following URL whilst logged in to Asana : http://app.asana.com/-/account_api . Remember that the API key will not be visible after it's created, so copy/paste it somewhere safe & never post it online!
 
+#### GetTokenFromXMLFile node
+This node reads the Asana token from an XML file. It takes in only 1 input :
+```
+1. filePath - the full path to the XML file containing the Asana token. I suggest placing this on your organisation's network somewhere for easy re-use.
+```
+
+
 ## Prerequisites
 
 This project requires the following applications or libraries be installed :
@@ -99,7 +149,7 @@ This project requires the following applications or libraries be installed :
 Dynamo : version 1.3 or later
 ```
 ```
-.Net : version 4.5 or later
+.Net : version 4.6.1 or later
 ```
 
 Please note the project has no dependency to Revit and its APIs, so it will happily run in Dynamo Sandbox or Dynamo Studio.
@@ -110,7 +160,7 @@ These instructions will get you a copy of the project up and running on your loc
 
 As a prerequisite, this project was authored in and requires :
 ```
-Visual Studio : version 2015 or later
+Visual Studio : version 2017 or later
 ```
 
 ## Get your development copy of DynAsana
@@ -139,7 +189,7 @@ The `DynAsana` project relies on a few community-published NuGet packages as lis
 
 ## Contributing
 
-Please read [CONTRIBUTING.md](https://github.com/radumg/DynAsana/CONTRIBUTING.md) for details the code of conduct, and the process for submitting pull requests.
+Please read [CONTRIBUTING.md](https://github.com/radumg/DynAsana/CONTRIBUTING.md) for details on how to contribute to this package. Please also read the [CODE OF CONDUCT.md](https://github.com/radumg/DynAsana/CODE_OF_CONDUCT.md).
 
 ## Versioning & Releases