Update Aug 29th 2019: Hyperledger Composer has been deprecated. Please see the README for more information.

BusinessNetworkConnection (Client API)

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

Inherited methods