Overview - Common API - Client API - Admin API - Runtime API
BusinessNetworkConnection
Use this class to connect to and then interact with a deployed Business Network Definition. Use the AdminConnection class in the composer-admin module to deploy BusinessNetworksDefinitions.
Details
Extends EventEmitter
Module client
Method Summary
Name | Returns | Description |
---|---|---|
addAssetRegistry | Promise |
Adds a new asset registry |
addParticipantRegistry | Promise |
Adds a new participant registry |
assetRegistryExists | Promise |
Determines whether an asset registry exists |
bindIdentity | Promise |
Bind an existing identity to the specified participant |
buildQuery | Query |
Build a query ready for later execution |
connect | Promise |
Connects to a business network using a business network card, and authenticates to the Hyperledger Fabric |
constructor | void |
Creates an instance of the BusinessNetworkConnection class |
disconnect | Promise |
Disconnects from the Hyperledger Fabric |
getAllAssetRegistries | Promise |
Gets a list of all existing asset registries |
getAllParticipantRegistries | Promise |
Gets a list of all existing participant registries |
getAllTransactionRegistries | Promise |
Gets a list of all existing transaction registries |
getAssetRegistry | Promise |
Gets an existing asset registry |
getBusinessNetwork | BusinessNetworkDefinition |
Gets the currently connected business network |
getHistorian | Promise |
Gets the historian |
getIdentityRegistry | Promise |
Gets the identity registry |
getNativeAPI | void |
Get the native API for this connection |
getParticipantRegistry | Promise |
Gets an existing participant registry |
getRegistry | Promise |
Given a fully qualified name, works out and looks up the registry that this resource will be found in |
getTransactionRegistry | Promise |
Gets an existing transaction registry |
issueIdentity | Promise |
Issue an identity with the specified name and map it to the specified participant |
participantRegistryExists | Promise |
Determines whether a participant registry exists |
ping | Promise |
Test the connection to the runtime and verify that the version of the runtime is compatible with this level of the client node |
query | Promise |
Execute a query defined in a Composer query file, or execute a query built with buildQuery |
revokeIdentity | Promise |
Revoke the specified identity by removing any existing mapping to a participant |
submitTransaction | Promise |
Submit a transaction for processing by the currently connected business network |
transactionRegistryExists | Promise |
Determines whether a transaction registry exists |
Method Details
new BusinessNetworkConnection()
Creates an instance of the BusinessNetworkConnection class. Must be called to connect to a deployed BusinessNetworkDefinition.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
options | Object | Yes | an optional set of options to configure the instance. |
Sub-options
Name | Type | Mandatory | Description |
---|---|---|---|
options.cardStore | BusinessNetworkCardStore | Yes | specify a card store implementation to use. |
getBusinessNetwork
BusinessNetworkDefinition getBusinessNetwork( )
Gets the currently connected business network. Business Network Definition.
Returns
BusinessNetworkDefinition - the business network definition
Parameters
No parameters
Example
const connection = new BusinessNetworkConnection();
const definition = await connection.connect('admin@network-name');
console.log(definition === connection.getBusinessNetwork()); // true
getAllAssetRegistries
Promise getAllAssetRegistries( [boolean includesystem] )
Gets a list of all existing asset registries.
Returns
Promise - A promise that will be resolved with a list of existing asset registries.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
includeSystem | boolean | Yes | if true the returned list will include the system transaction registries (optional, default to false) |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const assetRegistries = await connection.getAllAssetRegistries();
getAssetRegistry
Promise getAssetRegistry( string id )
Gets an existing asset registry.
Returns
Promise - A promise that will be resolved with the existing AssetRegistry, or rejected if it does not exist.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the asset registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const sampleAssetRegistry = await connection.getAssetRegistry('org.example.SampleAsset');
assetRegistryExists
Promise assetRegistryExists( string id )
Determines whether an asset registry exists.
Returns
Promise - A promise that will be resolved with a boolean indicating whether the AssetRegistry exists.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the asset registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const exists = await connection.assetRegistryExists('org.example.SampleAsset');
if (exists) {
// logic here...
}
addAssetRegistry
Promise addAssetRegistry( string id, string name )
Adds a new asset registry.
Returns
Promise - A promise that will be resolved with the new AssetRegistry after it has been added.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the asset registry |
name | string | Yes | The name of the asset registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
await connection.addAssetRegistry('registryId', 'registryName');
getAllParticipantRegistries
Promise getAllParticipantRegistries( [boolean includesystem] )
Gets a list of all existing participant registries.
Returns
Promise - A promise that will be resolved with a list of existing participant registries.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
includeSystem | boolean | Yes | if true the returned list will include the system transaction registries (optional, default to false) |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const participantRegistries = await connection.getAllParticipantRegistries();
getParticipantRegistry
Promise getParticipantRegistry( string id )
Gets an existing participant registry.
Returns
Promise - A promise that will be resolved with the existing ParticipantRegistry, or rejected if it does not exist.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the participant registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const sampleParticipantRegistry = await connection.getParticipantRegistry('org.example.SampleParticipant');
participantRegistryExists
Promise participantRegistryExists( string id )
Determines whether a participant registry exists.
Returns
Promise - A promise that will be resolved with a boolean indicating whether the ParticipantRegistry exists.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the participant registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const exists = await connection.participantRegistryExists('org.example.SampleParticipant');
if (exists) {
// logic here...
}
addParticipantRegistry
Promise addParticipantRegistry( string id, string name )
Adds a new participant registry.
Returns
Promise - A promise that will be resolved with the new ParticipantRegistry after it has been added.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the participant registry |
name | string | Yes | The name of the participant registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
await connection.addParticipantRegistry('registryId', 'registryName');
getTransactionRegistry
Promise getTransactionRegistry( string id )
Gets an existing transaction registry.
Returns
Promise - A promise that will be resolved with the existing TransactionRegistry, or rejected if it does not exist.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the transaction registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const sampleTransactionRegistry = await connection.getTransactionRegistry('org.example.SampleTransaction');
getAllTransactionRegistries
Promise getAllTransactionRegistries( [boolean includesystem] )
Gets a list of all existing transaction registries.
Returns
Promise - A promise that will be resolved with a list of existing transaction registries.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
includeSystem | boolean | Yes | if true the returned list will include the system transaction registries (optional, default to false) |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const transactionRegistries = await connection.getAllTransactionRegistries();
transactionRegistryExists
Promise transactionRegistryExists( string id )
Determines whether a transaction registry exists.
Returns
Promise - A promise that will be resolved with a boolean indicating whether the TransactionRegistry exists.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the transaction registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const exists = await connection.transactionRegistryExists('org.example.SampleTransaction');
if (exists) {
// logic here...
}
getHistorian
Promise getHistorian( )
Gets the historian.
Returns
Promise - A promise that will be resolved with the Historian.
Parameters
No parameters
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const historian = await connection.getHistorian();
getIdentityRegistry
Promise getIdentityRegistry( )
Gets the identity registry.
Returns
Promise - A promise that will be resolved with the IdentityRegistry.
Parameters
No parameters
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const identityRegistry = await connection.getIdentityRegistry();
connect
Promise connect( String cardname, [Object additionalconnectoptions] )
Connects to a business network using a business network card, and authenticates to the Hyperledger Fabric.
Returns
Promise - A promise that will be resolved with a BusinessNetworkDefinition that indicates the connection is completed.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
cardName | String | Yes | businessNetworkCard Name (must have been imported already) |
additionalConnectOptions | Object | Yes | Additional configuration options supplied at runtime that override options set in the connection profile, which will override those in the specified connection profile. |
Example
const connection = new BusinessNetworkConnection();
const definition = await connection.connect('admin@network-name');
getRegistry
Promise getRegistry( String fullyqualifiedname )
Given a fully qualified name, works out and looks up the registry that this resource will be found in. This only gives back the default registry - it does not look in any application defined registry.
Returns
Promise - A promise that will be resolved with the registry that this fully qualified name could be found in by default.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
fullyQualifiedName | String | Yes | The fully qualified name of the resource registry |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const sampleAssetRegistry = await connection.getRegistry('org.example.SampleAsset');
const sampleParticipantRegistry = await connection.getRegistry('org.example.SampleParticipant');
const sampleTransactionRegistry = await connection.getRegistry('org.example.SampleTransaction');
disconnect
Promise disconnect( )
Disconnects from the Hyperledger Fabric.
Returns
Promise - A promise that will be resolved when the connection is terminated.
Parameters
No parameters
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
// Connected.
await connection.disconnect();
// Disconnected.
submitTransaction
Promise submitTransaction( Resource transaction, [Object additionalconnectoroptions] )
Submit a transaction for processing by the currently connected business network.
Returns
Promise - A promise that will be fulfilled when the transaction has been processed.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
transaction | Resource | Yes | The transaction to submit. Use newTransaction to create this object. |
additionalConnectorOptions | Object | Yes | Additional connector specific options for this transaction. |
Example
const connection = new BusinessNetworkConnection();
const definition = await connection.connect('admin@network-name');
const factory = definition.getFactory();
const transaction = factory.newTransaction('org.example', 'SampleTransaction');
await connection.submitTransaction(transaction);
buildQuery
Query buildQuery( string query )
Build a query ready for later execution. The specified query string must be written in the Composer Query Language. This functionality is Blockchain platform dependent. For example, when a Composer business network is deployed to Hyperledger Fabric v1.0, Hyperledger Fabric must be configured with the CouchDB database for the world state.
Returns
Query - The built query, which can be passed in a call to query.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
query | string | Yes | The query string, written in the Composer Query Language. |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const query = connection.buildQuery('SELECT org.example.SampleAsset WHERE (value == _$inputValue)');
const assets = await connection.query(query, { inputValue: 'blue' })
query
Promise query( string; Query query, [Object parameters] )
Execute a query defined in a Composer query file, or execute a query built with buildQuery. This functionality is Blockchain platform dependent. For example, when a Composer business network is deployed to Hyperledger Fabric v1.0, Hyperledger Fabric must be configured with the CouchDB database for the world state.
Returns
Promise - A promise that will be resolved with an array of Resource representing the resources returned by the query.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
query | string; Query | Yes | The name of the query, or a built query. |
parameters | Object | Yes | The parameters for the query. |
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
const assets = await query('Q1', { inputValue: 'blue' })
ping
Promise ping( )
Test the connection to the runtime and verify that the version of the runtime is compatible with this level of the client node.js module.
Returns
Promise - A promise that will be fulfilled when the connection has been tested. The promise will be rejected if the version is incompatible.
Parameters
No parameters
Example
const connection = new BusinessNetworkConnection();
await connection.connect('admin@network-name');
await connection.ping();
issueIdentity
Promise issueIdentity( Resource; Relationship; string participant, string identityname, [object options] )
Issue an identity with the specified name and map it to the specified participant.
Returns
Promise - A promise that will be fulfilled when the identity has been added to the specified participant. The promise will be rejected if the participant does not exist, or if the identity is already mapped to another participant.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
participant | Resource; Relationship; string | Yes | The participant, a relationship to the participant, or the fully qualified identifier of the participant. The participant must already exist. |
identityName | string | Yes | The name for the new identity. |
options | object | Yes | Options for the new identity. |
Sub-options
Name | Type | Mandatory | Description |
---|---|---|---|
options.issuer | boolean | Yes | Whether or not the new identity should have permissions to create additional new identities. False by default. |
bindIdentity
Promise bindIdentity( Resource; string participant, string certificate )
Bind an existing identity to the specified participant.
Returns
Promise - A promise that will be fulfilled when the identity has been added to the specified participant. The promise will be rejected if the participant does not exist, or if the identity is already mapped to another participant.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
participant | Resource; string | Yes | The participant, or the fully qualified identifier of the participant. The participant must already exist. |
certificate | string | Yes | The certificate for the existing identity. |
revokeIdentity
Promise revokeIdentity( Resource; string identity )
Revoke the specified identity by removing any existing mapping to a participant.
Returns
Promise - A promise that will be fulfilled when the identity has been removed from the specified participant. The promise will be rejected if the participant does not exist, or if the identity is not mapped to the participant.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
identity | Resource; string | Yes | The identity, or the identifier of the identity. |
getNativeAPI
getNativeAPI( )
Get the native API for this connection. The native API returned is specific to the underlying blockchain platform, and may throw an error if there is no native API available.
Parameters
No parameters