From c1ccdb49c68886b1c2dd6bc1d4d2b24601dd9c22 Mon Sep 17 00:00:00 2001 From: EdProsser Date: Thu, 15 Jun 2017 09:32:24 +0100 Subject: [PATCH] Short branch (#1277) * Updates for work * Adding Installing Index to ToC * Removing Fabric Composer name * Removing Fabric composer name * Moving images for REST API doc * Fabric Composer Name removal * Fabric Composer name removal * Other name changes (Stack Overflow, GitHub, Rocket.Chat, JavaScript) * wording updates and bug splats * ToC Updates * HLv1 docs updates, couple more bug splats. * Last edit for HLv1 * Whoops, bug splat * Another bug splat... * Quick fixes prereqs navbar * intro diagram fix and bug fixes * Fixes and updates * Rollback optional script for v1.0 * QoL changes and rollback changes - Quickstart * Link fixes * Atom links fix, formatting fix * Odd formatting fix. * Name change and codeblock fix * More odd formatting fixes * Ubuntu root user doc fix + draft of bnd doc changes * update for CLI define + deploy BNA * last bnd update * Events and bug fixes * Last event thing * Updates for #803 and #822 * removing unnecessary stuff * Undeploy support #673 * Clarifications on undeploy * Commit? * Revert "Commit?" This reverts commit 909456849dddc1b02c4e769629033031dd8c1780. * Quick Fixes * Quick fix for connection profile keyvalstore * Updates to show events docs in ToC * Quick fixes * Last minute docs updates. * changes from issue #912 Signed-off-by: Edward Prosser * Version 1 auto-generating landing pages * Docs Updates week 2 * 1 more set of updates * last changes * HLFV1 Beta and Query (#1247) (#1255) System and unit tests Rich query support for fabric V1 alpha Alpha 2 Support * Move HLF v0.6 to use Duktape instead of Otto (#1257) * Connection profile, identity import, logic.js * Query v0.1 * Connection profile, Query, Security, Dev Guide * Security updates for local playground * Last minute updates --- .../jekylldocs/business-network/bnd-deploy.md | 14 +++- .../jekylldocs/business-network/query.md | 70 +++++++++++++++++++ .../installing/using-playground-locally.md | 13 ++++ .../reference/composer.identity.import.md | 10 +-- .../jekylldocs/reference/connectionprofile.md | 22 +++--- .../jekylldocs/tutorials/developer-guide.md | 38 +++++----- .../jekylldocs/tutorials/playground-guide.md | 6 +- 7 files changed, 135 insertions(+), 38 deletions(-) create mode 100644 packages/composer-website/jekylldocs/business-network/query.md diff --git a/packages/composer-website/jekylldocs/business-network/bnd-deploy.md b/packages/composer-website/jekylldocs/business-network/bnd-deploy.md index da5a8f2a94..5758e399ce 100644 --- a/packages/composer-website/jekylldocs/business-network/bnd-deploy.md +++ b/packages/composer-website/jekylldocs/business-network/bnd-deploy.md @@ -16,11 +16,23 @@ Once the BNA file has been created it can be deployed to a runtime using the `co For example: - composer network deploy -p connectionProfileName -a .bna + composer network deploy -p connectionProfileName -a .bna -i -s To update the definition of an already deployed business network use the `composer network update` CLI command. +## Deploying business networks to {{site.data.conrefs.hlf_full}} Beta + +In {{site.data.conrefs.hlf_full}} Beta peers now enforce the concepts of admins and members. Admin user's identities and crypto material must be available to the peer at deployment. To make that identity and its crypto material available, your must import it to your local `keyValStore` directory before deploying the business network. To import the identity, use the [`composer identity import` command](../reference/composer.identity.import.html). When importing an identity, you do not assign it a secret, however the `composer network deploy` command requires a secret. If you are using an imported identity, you can enter any value for the secret. + +When connecting to the peer you must specify an identity where the userID contains the text `admin`, for example, `PeerAdmin`, `myadmin`, or `AdminPeer` are all valid userID's. Peers in different organizations may have different admin users. Only an admin user of peer's organization will be able to deploy a business network to their peers. + +These security changes mean that {{site.data.conrefs.composer_full}} cannot support older versions of {{site.data.conrefs.hlf_full}} v1.0 (e.g. alpha 1). + +### Deploying business networks using Playground locally + +When deploying a business network to {{site.data.conrefs.hlf_full}} Beta using the Playground locally, you must follow the process above to connect using the peer admin identity. However, in order to create identities and interact with your business network in the Playground, you must use the certificate authority admin identity. + ## References * [**Composer CLI commands**](../reference/commands.html) diff --git a/packages/composer-website/jekylldocs/business-network/query.md b/packages/composer-website/jekylldocs/business-network/query.md new file mode 100644 index 0000000000..811d9a0a69 --- /dev/null +++ b/packages/composer-website/jekylldocs/business-network/query.md @@ -0,0 +1,70 @@ +--- +layout: default +title: Querying Business Network Data +category: tasks +section: business-network +sidebar: sidebars/businessnetworks.md +excerpt: Using {{site.data.conrefs.hlf_full}} and CouchDB, you can query assets in the stored world-state and return listed assets by using a transaction processor function. +--- + +# Querying business network data + +>Warning +The status of this feature is experimental. You **must** use Hyperledger Composer v0.8+ with the the HLFv1 runtime to use queries. We welcome feedback and comments while we continue to iterate upon query functionality. The API may change based on the feedback received. In future releases we plan to extend this feature with a Composer specific query language, and data-binding to assets, participants and transactions. + +{{site.data.conrefs.hlf_full}} v1.0 can be configured to store the world-state in a CouchDB database. CouchDB is a JSON document store, so all data in the world-state is persisted as JSON documents, including Composer assets, participants and transactions. + +When {{site.data.conrefs.hlf_full}} is used in CouchDB mode chaincode can execute complex (content-based) queries against the world-state data. The queries are written in the Mango query language, the native CouchDB query language. + +An example Mango _selector_ query: + var q = { + selector: { + size: 'SMALL' + } + }; + +This query will select all JSON documents in the document store that contain the property `size` that has the value `SMALL`. Please refer to the CouchDB documentation for the [query syntax for Mango queries](http://docs.couchdb.org/en/2.0.0/api/database/find.html). Note that CouchDB ships with a powerful web interface called [Fauxton](http://couchdb.apache.org/fauxton-visual-guide/). You can use Fauxton to inspect the documents in the document store, run queries, view results etc. + +### Running Native CouchDB Mango Queries from Transaction Processor Functions + +The Composer runtime API includes the `queryNative(queryString)` method, allowing transaction processor functions to submit native Mango queries to CouchDB. Composer will execute the query against CouchDB, returning a promise to a JS Object that captures the results of running the query. + +The JS Object returned is composed of an array of objects, each with a `Key` and `Record` property. `Key` is a string that represents the key of the document in the document store. `Record` is a JS Object that captures the data for the document itself. + +### Example + +The example below runs a content-based query to select all `SMALL` marbles, verifies the number of marbles returned, and that they are indeed all `SMALL`. +``` +/** + * Executes a CouchDB query and checks the results. + * @param {org.fabric_composer.marbles.QueryMarbleByOwner} transaction + * @transaction + * @return {Promise} a promise to the results of transaction processing + */ +function onQueryMarbleByOwner(transaction) { + var factory = getFactory(); + // create the query + var q = { + selector: { + size: 'SMALL' + } + }; + return queryNative(JSON.stringify(q)) + .then(function (resultArray) { + print('TP function received query result: ', JSON.stringify(resultArray)); + if (resultArray.length !== 5) { + throw new Error('The incorrect number of marbles found: ', resultArray.length); + } + for (var x = 0; x < resultArray.length; x++) { + var currentResult = resultArray[x]; + if (currentResult.Record.size !== 'SMALL') { + throw new Error('Query returned a marble that is not SMALL!', currentResult.Record); + } + } + }); +} +``` + +Using a selector it is possible to query all assets of a given type, with a given set of properties, and then to convert them back into Composer resources using `getSerializer().fromJSON(jsObject)`. Once the JS object returned by a query have been converted back into a Composer object it can be updated and persisted back into an asset registry. + +>Note that in the future Composer will define a query language expressed in terms of assets, participants and transactions and automatically marshall the JS objects returned by CouchDB to the corresponding Composer modelled types. diff --git a/packages/composer-website/jekylldocs/installing/using-playground-locally.md b/packages/composer-website/jekylldocs/installing/using-playground-locally.md index 0f5fc182b6..730c3569a8 100644 --- a/packages/composer-website/jekylldocs/installing/using-playground-locally.md +++ b/packages/composer-website/jekylldocs/installing/using-playground-locally.md @@ -42,6 +42,19 @@ docker images -aq | xargs docker rmi -f By default, the Web Browser connection profile is in use (for developing and testing in browser memory). To connect instead to the {{site.data.conrefs.hlf_full}} instance created in the previous step, click the globe icon in the top right of the UI to visit the Connection Profiles panel and change your active profile to 'hlfabric'. +## Deploying business networks to {{site.data.conrefs.hlf_full}} Beta + +In {{site.data.conrefs.hlf_full}} Beta peers now enforce the concepts of admins and members. Admin user's identities and crypto material must be available to the peer at deployment. To make that identity and its crypto material available, your must import it to your local `keyValStore` directory before deploying the business network. To import the identity, use the [`composer identity import` command](../reference/composer.identity.import.html). When importing an identity, you do not assign it a secret, however the `composer network deploy` command requires a secret. If you are using an imported identity, you can enter any value for the secret. + +When connecting to the peer you must specify an identity where the userID contains the text `admin`, for example, `PeerAdmin`, `myadmin`, or `AdminPeer` are all valid userID's. Peers in different organizations may have different admin users. Only an admin user of peer's organization will be able to deploy a business network to their peers. + +These security changes mean that {{site.data.conrefs.composer_full}} cannot support older versions of {{site.data.conrefs.hlf_full}} v1.0 (e.g. alpha 1). + +### Deploying business networks using Playground locally + +When deploying a business network to {{site.data.conrefs.hlf_full}} Beta using the Playground locally, you must follow the process above to connect using the peer admin identity. However, in order to create identities and interact with your business network in the Playground, you must use the certificate authority admin identity. + + --- - After processing, you should now see the transaction in the transaction registry. ![Transaction registry](../assets/img/tutorials/developer/tx_registry.png) @@ -624,14 +626,8 @@ If you navigate to this URL and press the "Assets" drop down (at the top-right o Well done, you've now completed this tutorial and we hope you now have a much better idea how the capabilities fit together. You can start hacking on the skeleton Angular application to create the next industry defining blockchain-based application! -## Related Concepts +## Related Links [Business Network Definition](../business-network/businessnetworkdefinition.html) - -## Related Tasks - [Deploying a business network](../business-network/bnd-deploy.html) - -## Related Reference - [Network deploy command](../reference/composer.network.deploy.html) diff --git a/packages/composer-website/jekylldocs/tutorials/playground-guide.md b/packages/composer-website/jekylldocs/tutorials/playground-guide.md index 178324abdb..0a311e5439 100644 --- a/packages/composer-website/jekylldocs/tutorials/playground-guide.md +++ b/packages/composer-website/jekylldocs/tutorials/playground-guide.md @@ -22,11 +22,11 @@ Before beginning, you will need: --- ## Let's get started - Importing the Car Auction sample -1. Open the [{{site.data.conrefs.composer_short}} Playground](https://composer-playground.mybluemix.net). On the left are three file types: a script file, `lib/logic.js` which represents transaction logic, a model file, `lib/org.example.biznet.cto` which defines the participants assets and transactions of the business network, and an access control file, `permissions.acl` which defines the access different participants have. +1. Open the [{{site.data.conrefs.composer_short}} Playground](https://composer-playground.mybluemix.net). On the left are three file types: a script file, `lib/sample.js` which represents transaction logic, a model file, `lib/org.example.biznet.cto` which defines the participants assets and transactions of the business network, and an access control file, `permissions.acl` which defines the access different participants have. 2. To get switch out the sample business network click **Import/Replace**. This dialog allows you to import your own business network archive `.bna` files, or to import our premade business network samples. For now we'll use a pre-built sample from the {{site.data.conrefs.composer_short}} GitHub repository. Click **Authenticate with GitHub** then log into your GitHub account and click **Authorize application**. -3. From the menu, select **carauction-network** and click **Deploy**. This imports the car auction sample business network into your Playground instance. In the model file `lib/org.example.vehicle.auction.cto` there are the definitions of asset types, participant types, and transactions. The entries in the `.cto` file define the expected format of each asset, participant, and transaction. The script file `lib/logic.js` contains JavaScript +3. From the menu, select **carauction-network** and click **Deploy**. This imports the car auction sample business network into your Playground instance. In the model file `lib/org.example.vehicle.auction.cto` there are the definitions of asset types, participant types, and transactions. The entries in the `.cto` file define the expected format of each asset, participant, and transaction. The script file `lib/sample.js` contains JavaScript which controls the transactions, in this script file, there is JavaScript logic controlling the `Close Bidding` and `Make Offer` transactions. ### Setting up the auction @@ -84,7 +84,7 @@ which controls the transactions, in this script file, there is JavaScript logic 4. When you've placed as many bids as you like, the next step is to submit the *CloseBidding* transaction to close the auction. The *CloseBidding* transaction pays the previous owner of the *Vehicle* asset listed in the *VehicleListing* the current highest offer, changes the `state` of the listing to `SOLD`, and transfers ownership of the *Vehicle* asset, as listed in the `owner` property, to the highest bidder. To submit the *CloseBidding* transaction, click **Submit Transaction** and enter the `listingId` which corresponds to the *VehicleListing*. Click **Submit** to submit the transaction. Once the transaction has been submitted, you can check the *Vehicle* asset's `owner` property to ensure that it has changed, as well as checking the `balance` of the previous and new owner of the car, and the *VehicleListing* `state`. -5. You've successfully run the `carauction-network` {{site.data.conrefs.composer_short}} sample! If you want to continue to use this business network in future tutorials or for testing, click **Export** in the **Define** tab to download a Business Network Archive `.bna` file. A `.bna` file contains all files listed in the business network, in this example, `README.md`, `lib/logic.js`, `lib/org.example.vehicle.auction.cto`, and `permissions.acl`. +5. You've successfully run the `carauction-network` {{site.data.conrefs.composer_short}} sample! If you want to continue to use this business network in future tutorials or for testing, click **Export** in the **Define** tab to download a Business Network Archive `.bna` file. A `.bna` file contains all files listed in the business network, in this example, `README.md`, `lib/sample.js`, `lib/org.example.vehicle.auction.cto`, and `permissions.acl`. If you want to continue to modify your business network, you could add some new fields to asset types in the business network definition, for example, make or model for *Vehicle* assets.