diff --git a/README.md b/README.md index 05656a299f..ae79862c44 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,8 @@ Suggested reading list is: - [Introduction](https://hyperledger.github.io/composer/introduction/introduction.html) - [Introduction Video](https://www.youtube.com/watch?v=fdFUsrsv5iw&t=23s) -- [Quick Start](https://hyperledger.github.io/composer/installing/quickstart.html) -- [Quick Start Video](https://www.youtube.com/watch?v=pEHBIfb_iqc&t=5s) -- [Tutorials](https://hyperledger.github.io/composer/tutorials/tutorialindex.html) +- [Quick Start](https://hyperledger.github.io/composer/installing/installing-index.html) +- [Tutorials](https://hyperledger.github.io/composer/tutorials/tutorials.html) # Getting in touch diff --git a/packages/composer-website/jekylldocs/_includes/sidebars/accordion-toc0.md b/packages/composer-website/jekylldocs/_includes/sidebars/accordion-toc0.md index 6b601698c4..444a62f723 100644 --- a/packages/composer-website/jekylldocs/_includes/sidebars/accordion-toc0.md +++ b/packages/composer-website/jekylldocs/_includes/sidebars/accordion-toc0.md @@ -3,9 +3,9 @@ {% if page.index-order %} {% capture mods %}{{ page.index-order | modulo:100 }}{% endcapture %} {% if mods == "0" %} -- [{{ page.title }}]({{site.url}}{{page.url}}.html) +- [{{ page.title }}](../{{page.url}}.html) {% elsif mods != "0" %} - - [{{page.title}}]({{site.url}}{{page.url}}.html) + - [{{page.title}}](../{{page.url}}.html) {% endif %} {% endif %} {% endfor %} diff --git a/packages/composer-website/jekylldocs/_includes/sidebars/businessnetworks.md b/packages/composer-website/jekylldocs/_includes/sidebars/businessnetworks.md deleted file mode 100644 index c66460ee59..0000000000 --- a/packages/composer-website/jekylldocs/_includes/sidebars/businessnetworks.md +++ /dev/null @@ -1,17 +0,0 @@ -- [Introduction](../introduction/introduction.html) -- [Installing](../installing/installing-index.html) -- [Tutorials](../tutorials/tutorials.html) -- [Developing Business Networks](../business-network/business-network-index.html) - - [What is a business network definition?](../business-network/businessnetworkdefinition.html) - - [Creating a business network definition](../business-network/bnd-create.html) - - [Deploying and updating](../business-network/bnd-deploy.html) - - [Emitting events](../business-network/publishing-events.html) - - [Testing](../business-network/testing.html) - - [Publishing to npm](../business-network/bnd-publish.html) - - [Querying Business Network Data](../business-network/query.html) -- [Developing Applications](../applications/applications-index.html) -- [Integrating Existing Systems](../integrating/integrating-index.html) -- [Managing and Operating](../managing/managingindex.html) -- [Diagnosing Problems](../problems/diagnostics.html) -- [Reference](../reference/reference-index.html) -- [Support](../support/index.html) diff --git a/packages/composer-website/jekylldocs/business-network/bnd-deploy.md b/packages/composer-website/jekylldocs/business-network/bnd-deploy.md index ff7642d4c2..6d265947a6 100644 --- a/packages/composer-website/jekylldocs/business-network/bnd-deploy.md +++ b/packages/composer-website/jekylldocs/business-network/bnd-deploy.md @@ -22,7 +22,7 @@ For example: 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}} v1.0 RC 1 +## Deploying business networks to {{site.data.conrefs.hlf_full}} RC 1 In {{site.data.conrefs.hlf_full}} v1.0 RC 1 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. @@ -34,6 +34,7 @@ Due to many breaking API changes between {{site.data.conrefs.hlf_full}} alpha 1 When deploying a business network to {{site.data.conrefs.hlf_full}} v1.0 RC 1 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/managing/connector-information.md b/packages/composer-website/jekylldocs/managing/connector-information.md new file mode 100644 index 0000000000..55cd1f685b --- /dev/null +++ b/packages/composer-website/jekylldocs/managing/connector-information.md @@ -0,0 +1,17 @@ +--- +layout: default +title: Connector Specific Information +category: tasks +section: managing +sidebar: sidebars/accordion-toc0.md +excerpt: +--- + +# Connector Specific Information + +{{site.data.conrefs.composer_full}} is designed to be platform-agnostic + + +## {{site.data.conrefs.hlf_full}} + +There are several cases where information specific to {{site.data.conrefs.hlf_full}} must be included in {{site.data.conrefs.composer_full}} commands, including `composer network deploy`, and `composer identity issue`. diff --git a/packages/composer-website/jekylldocs/problems/diagnostics.md b/packages/composer-website/jekylldocs/problems/diagnostics.md index 8438988996..df1cfb2efb 100644 --- a/packages/composer-website/jekylldocs/problems/diagnostics.md +++ b/packages/composer-website/jekylldocs/problems/diagnostics.md @@ -10,13 +10,41 @@ index-order: 800 # Diagnosing Problems +Composer uses the Winston logging module by default - and will use the Config module to look for any configuration information. If none is found, then a set of defaults will be used. + +The config module does write out a warning, if there are no configuration files set. Eg. `WARNING: No configurations found in configuration directory`. This can be suppressed with an environment variable if you are happy with the defaults and don't wish to use config in your application. See more information [here](https://github.com/lorenwest/node-config/wiki/Environment-Variables#suppress_no_config_warning). + + +# Diagnosing Problems + If something should ever go wrong with an application, what should you do about getting diagnostics? Let's look at the `digitalproperty-app` sample, and use that to explain how to get diagnostics out of the framework. ->Please note: This is a framework - so your application will need to have it's own logging framework. Also, your application could also have configuration information to control {{site.data.conrefs.composer_full}}'s own logging. Composer uses the Winston logging module by default - and will use the Config module to look for any configuration information. If none is found, then a set of defaults will be used. - -The config module does write out a warning, if there are no configuration files set. Eg. `WARNING: No configurations found in configuration directory`. This can be suppressed with an environment variable if you are happy with the defaults and don't wish to use config in your application. See more information [here](https://github.com/lorenwest/node-config/wiki/Environment-Variables#suppress_no_config_warning). +>Please note: This is a framework - so your application will need to have it's own logging framework. Also, your application could also have configuration information to control {{site.data.conrefs.composer_full}}'s own logging. There are two containers that are relevant to logging; @@ -129,3 +157,4 @@ cat ~/.composer-connection-profiles/defaultProfile/connection.json }; ``` By inspection, the ids match for the carauction-network therefore we know now which chaincode container is which. +--> diff --git a/packages/composer-website/jekylldocs/reference/acl_language.md b/packages/composer-website/jekylldocs/reference/acl_language.md index cdd4734102..d1c3a148f6 100644 --- a/packages/composer-website/jekylldocs/reference/acl_language.md +++ b/packages/composer-website/jekylldocs/reference/acl_language.md @@ -13,13 +13,92 @@ excerpt: The [**Hyperledger Composer access control language**](./acl_language.h {{site.data.conrefs.composer_full}} includes an access control language (ACL) that provides declarative access control over the elements of the domain model. By defining ACL rules you can determine which users/roles are permitted to create, read, update or delete elements in a business network's domain model. -### Evaluation of Access Control Rules +## Network Access Control + +{{site.data.conrefs.composer_full}} differentiates between access control for resources within a business network (business access control) and access control for network administrative changes (network access control). Business access control and network access control are both defined in the access control file (`.acl`) for a business network. + +Network access control uses the system namespace, which is implicitly extended by all resources in a business network; and grants or denies access to specific actions as defined below, and is intended to allow for more nuanced access to certain network-level operations. + +### What does network access control allow or disallow? + +Network access control affects the following CLI commands: + + +#### Composer Network + +**composer network deploy** + +Network access is required to use the CREATE operation for registries and networks. + +**composer network download** + +Network access is required to use the READ operation for registries and networks. + +**composer network list** + +Network access is required to use the READ operation for registries and networks. + +**composer network logLevel** + +Network access is required to use the UPDATE operation for networks. + +**composer network ping** + +Network access is required to use the READ operation on registries and networks. + +**composer network undeploy** + +Network access is required to use the DELETE operation on registries and networks. + +**composer network update** + +Network access is required to use the UPDATE or CREATE operation on registries, or the UPDATE operation on networks. + + +#### Composer Identity + +**composer network import** + +Network access is required to use the UPDATE operation on identity registries or the CREATE operation on identities. + +**composer network issue** + +Network access is required to use the UPDATE operation on identity registries or the CREATE operation on identities. + +**composer network revoke** + +Network access is required to use the UPDATE operation on identity registries or the DELETE operation on identities. + +#### Composer Participant + +**composer network add** + +Network access is required to use the CREATE operation on participants or the UPDATE operation on participant registries. + +### Granting network access control + +Network access is granted using the system namespace. The system namespace is always `org.hyperledger.composer.system`. + +The following access control rule will give all participants access to all operations and commands in the business network, including network access and business access. + +``` +rule AllAccess { + description: "AllAccess - grant everything to everybody" + participant: "org.hyperledger.composer.system.Participant" + operation: ALL + resource: "org.hyperledger.composer.system.**" + action: ALLOW +} +``` + + +## Evaluation of Access Control Rules Access control for a business network is defined by an ordered set of ACL rules. The rules are evaluated in order, and the first rule whose condition matches determines whether access is granted or denied. If no rule match then access is **denied**. ACL rules are defined in a file called `permissions.acl` in the root of the business network. If this file is missing from the business network then all access is **permitted**. -### Access Control Rule Grammar +## Access Control Rule Grammar There are two types of ACL rules: simple ACL rules and conditional ACL rules. Simple rules are used to control access to a namespace, asset or property of an asset by a participant type or participant instance. @@ -71,6 +150,7 @@ Multiple ACL rules may be defined that conceptually define a decision table. The **Resource** defines the things that the ACL rule applies to. This can be a class, all classes within a namespace, or all classes under a namespace. It can also be an instance of a class. Resource Examples: + - Namespace: org.example.* - Namespace (recursive): org.example.** - Class in namespace: org.example.Car @@ -86,7 +166,7 @@ Resource Examples: **Action** identifies the action of the rule. It must be one of: ALLOW, DENY. -### Examples +## Examples Example ACL rules (in evaluation order): diff --git a/packages/composer-website/jekylldocs/reference/cto_language.md b/packages/composer-website/jekylldocs/reference/cto_language.md index 1d3f87aeda..ed7b6c62b3 100644 --- a/packages/composer-website/jekylldocs/reference/cto_language.md +++ b/packages/composer-website/jekylldocs/reference/cto_language.md @@ -11,57 +11,92 @@ excerpt: The [**Hyperledger Composer modeling language**](./cto_language.html) i --- -{{site.data.conrefs.composer_full}} includes an Object-Oriented modeling language that is used to define -the domain model for a business network definition. +{{site.data.conrefs.composer_full}} includes an object-oriented modeling language that is used to define the domain model for a business network definition. A {{site.data.conrefs.composer_full}} CTO file is composed of the following elements: -1. A single namespace. All resource declarations within the file are implicitly -in this namespace. -2. Optional import declarations that import resources from other namespaces. -3. A set of resource definitions (see below). +1. A single namespace. All resource declarations within the file are implicitly in this namespace. +2. A set of resource definitions, encompassing assets, transactions, participants, and events. +3. Optional import declarations that import resources from other namespaces. -## Imports +## Organization and {{site.data.conrefs.composer_full}} System Namespaces -Use the `import` keyword with a fully-qualified type name to import a type from another namespace. Alternatively use the `.*` notation to import all the types from another namespace. +Your organization namespace is defined in the namespace line of your model (`.cto`) file, and all resources created are implicitly part of this namespace. -``` -import org.example.MyAsset -import org.example2.* -``` +As well as defining new classes of asset, participant, event, and transaction, there is a system namespace which contains the base definitions of asset, event, participant, and transaction. These base definitions are abstracts which are implicitly extended by all assets, events, participants, and transactions. -## Declarations of enumerated types +Represented as a `.cto` model file, the system namespace is as follows: ``` -/** -* An enumerated type -*/ -enum AnimalType { -o SHEEP_GOAT -o CATTLE -o PIG -o DEER_OTHER -} + namespace org.hyperledger.composer.system + abstract asset Asset { } + abstract participant Participant { } + abstract transaction Transaction { + o DateTime timestamp + } + abstract event Event { + o DateTime timestamp + } ``` +In the system namespace definitions, asset and participant have no required values. Events and transactions are defined by an eventId or transactionId and a timestamp. -## Declarations of Assets, Events, Participants, Transactions +>If you have defined an event or transaction including an eventId, transactionId, or timestamp, you must delete the eventId, transactionId, or timestamp properties. + + +## Declarations of resources + +Resources in {{site.data.conrefs.composer_full}} include: + +- Assets, Participants, Transactions, and Events. +- Enumerated Types. +- Concepts. +- Assets, Participants and Transactions are class definitions. The concepts of Asset, Participant and Transaction may be considered to be different stereotypes of the class type. -A class in {{site.data.conrefs.composer_full}} is referred to as a Resource Definition. Therefore an Asset (instance) has an Asset Definition. +A class in {{site.data.conrefs.composer_full}} is referred to as a Resource Definition, therefore an asset instance has an Asset Definition. A resource definition has the following properties: -1. A name -2. A namespace defined by the namespace of its parent file -3. An identifying field. For example, the Vehicle asset might be identified by -the vin field. Identifying fields must be Strings. -4. An optional super-type, which the resource definition extends. -5. An optional 'abstract' declaration, to indicate that this type cannot be created -6. A set of named fields (data owned by the resource, using a has-a relationship) -7. A set of relationships to other Composer types that are not owned by the resource -but that may be referenced from the resource. Relationships are unidirectional. +1. A namespace defined by the namespace of its parent file. The namespace of a `.cto` file implicitly applies to all resources created in it. +2. A name, for example `Vehicle`. If the resource is an asset or participant, it is followed by it's identifying field, if the resource is an event or transaction, the identifying field is set automatically. In this example, the asset is named `Vehicle` and the identifying field is `vin`. + + ``` + /** + * A vehicle asset. + */ + asset Vehicle identified by vin { + o String vin + } + ``` + +3. An identifying field. For example, the Vehicle asset might be identified by the `vin` field. Identifying fields must be Strings. *Note*: Events and transactions do not require an identifying field to be set, the identifying fields `eventId` and `transactionId` will be created automatically. +4. An optional super-type, which the resource definition extends. The resource will take all properties and fields required by the super-type and add any additional properties or fields from its own definition. + + ``` + /** + * A car asset. A car is related to a list of parts + */ + asset Car extends Vehicle { + o String model + --> Part[] Parts + } + ``` + +5. An optional 'abstract' declaration, to indicate that this type cannot be created. Abstract resources can be used as a basis for other classes to extend. Extensions of abstract classes do not inherit the abstract status. For example, the asset `Vehicle` defined above should never be created, as there should be more specific asset classes defined to extend it. + + ``` + /** + * An abstract Vehicle asset. + */ + abstract asset Vehicle identified by vin { + o String vin + } + ``` + +6. A set of named properties. The properties must be named, and the primitive data type defined.The properties and their data are owned by each resource, for example, a `Car` asset has a `vin`, and a `model` property, both of which are strings. +7. A set of relationships to other Composer types that are not owned by the resource but that may be referenced from the resource. Relationships are unidirectional. ``` /** @@ -93,8 +128,7 @@ but that may be referenced from the resource. Relationships are unidirectional. /** * An abstract event type */ - event BasicEvent identified by eventId { - o String eventId + event BasicEvent { } ``` @@ -102,8 +136,7 @@ but that may be referenced from the resource. Relationships are unidirectional. /** * An abstract transaction type for animal movements */ - abstract transaction AnimalMovement identified by transactionId { - o String transactionId + abstract transaction AnimalMovement { --> Animal animal } ``` @@ -117,35 +150,33 @@ but that may be referenced from the resource. Relationships are unidirectional. } ``` +### Declarations of enumerated types +Enumerated types are to define the potential content of properties of other resources. By using enumerated types, the expected content in a field can be restricted and controlled, reducing unexpected data. The following enumerated type declaration contains a list of roles. -## {{site.data.conrefs.composer_full}} System Namespace - -As well as defining new classes of asset, participant, event, and transaction, there is a system namespace which contains the base definitions of asset, event, participant, and transaction. These base definitions are abstracts which are implicitly extended by all assets, events, participants, and transactions. +``` +/** +* An enumerated type +*/ +enum product { +o DAIRY +o BEEF +o VEGETABLES +} +``` -Represented as a `.cto` model file, the system namespace is as follows: +When another resource is created, for example, a participant, a property of that resource can be defined to expect one of the enumerated types. ``` - namespace org.hyperledger.composer.system - abstract asset Asset { } - abstract participant Participant { } - abstract transaction Transaction identified by transactionId{ - o String transactionId - o DateTime timestamp - } - abstract event Event identified by eventId{ - o String eventId - o DateTime timestamp - } +participant Farmer identified by farmerId { + o String farmerId + o product primaryProduct ``` -In the system namespace definitions, asset and participant have no required values. Events and transactions are defined by an eventId or transactionId and a timestamp. - ->If you have defined an event or transaction including an eventId, transactionId, or timestamp, you must delete the eventId, transactionId, or timestamp properties. -## Concepts +### Concepts -Concepts are complex types (classes) that are not assets, participants or transactions. They are typically contained by an asset, participant or transaction. +Concepts are abstract classes that are not assets, participants or transactions. They are typically contained by an asset, participant or transaction. For example, below an abstract concept `Address` is defined, and then specialized into a `UnitedStatesAddress`. Note that concepts do not have an `identified by` field as they cannot be directly stored in registries or referenced in relationships. @@ -163,21 +194,20 @@ concept UnitedStatesAddress extends Address { ``` -## Primitive types +### Primitive types Composer resources are defined in terms of the following primitive types: -1. String : a UTF8 encoded String -2. Double : a double precision 64 bit numeric value -3. Integer : a 32 bit signed whole number -4. Long : a 64 bit signed whole number -5. DateTime : an ISO-8601 compatible time instance, with optional time zone -and UTZ offset -6. Boolean : a Boolean value, either true or false. +1. String: a UTF8 encoded String. +2. Double: a double precision 64 bit numeric value. +3. Integer: a 32 bit signed whole number. +4. Long: a 64 bit signed whole number. +5. DateTime: an ISO-8601 compatible time instance, with optional time zone and UTZ offset. +6. Boolean: a Boolean value, either true or false. -## Arrays +### Arrays -All types in Composer may be declared as arrays using the [] notation. Hence +All types in Composer may be declared as arrays using the [] notation. Integer[] integerArray @@ -188,7 +218,7 @@ Is an array of Integers stored in a field called 'integerArray'. While Is an array of relationships to the Animal type, stored in a field called 'incoming'. -## Relationships +### Relationships A relationship in the Composer language is a tuple composed of: @@ -208,7 +238,7 @@ Relationships must be *resolved* to retrieve an instance of the object being referenced. The act of resolution may result in null, if the object no longer exists or the information in the relationship is invalid. -## Field Validators +### Field Validators String fields may include an optional regular expression, which is used to validate the contents of the field. Careful use of field validators allows Composer to perform rich data validation, leading to fewer errors and less boilerplate code. @@ -250,3 +280,12 @@ asset Vehicle extends Base { o Customer customer } ``` + +## Imports + +Use the `import` keyword with a fully-qualified type name to import a type from another namespace. Alternatively use the `.*` notation to import all the types from another namespace. + +``` +import org.example.MyAsset +import org.example2.* +```