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

AdminConnection (Admin API)

Overview - Common API - Client API - Admin API - Runtime API

AdminConnection

This class creates an administration connection to a Hyperledger Composer runtime. The connection can then be used to:

  • Deploy BusinessNetworkDefinitions
  • Undeploy BusinessNetworkDefinitions
  • Update BusinessNetworkDefinitions
  • Send a ping message to the runtime to ensure it is running and correctly configured.
  • Store a connection profile document in the connection profile store

Note: that the methods on this class take the 'businessNetworkIdentifier'; this has to match the name given on the create call. An AdminConnection that has been connected to network-A can only be used to adminster network-A.

Instances of AdminConnections can be reused for different networks. Call disconnect(..) then connect(..). Calling an api after disconnect and before connect will give an error.

Details

  • Module admin

Method Summary

Name Returns Description
connect void Connects and logs in to the Hyperledger Fabric using a named connection profile
constructor void Create an instance of the AdminConnection class
deleteCard Promise Delete an existing card
disconnect Promise Disconnects this connection
exportCard Promise Exports an network card
getAllCards Promise List all Business Network cards
getLogLevel Promise Get the current logging level of a business network
getNativeAPI void Get the native API for this connection
hasCard Promise Has a existing card
importCard Promise Import a business network card
install Promise Installs a business network as chaincode to Hyperledger Fabric in preparation for the business network to be started
list Promise List all of the deployed business networks
ping Promise Test the connection to the runtime and verify that the version of the runtime is compatible with this level of the node
reset Promise Resets an existing BusinessNetworkDefinition on the Hyperledger Fabric
setLogLevel Promise Set the logging level of a business network
start Promise Starts a business network within the runtime previously installed to the Hyperledger Fabric with the same name as the business network to be started
undeploy Promise Undeploys a business network
upgrade Promise Upgrades an existing business network to a later level

Method Details

new AdminConnection()

Create an instance of the AdminConnection class. The default cardstore is a filesystem based one that stores files in ~/.composer

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.

importCard

Promise importCard( String name, IdCard card )

Import a business network card. If a card of this name exists, it is replaced.

Returns

Promise - Resolved when the card is imported, resolves to true if updated, false if added.

Parameters

Name Type Mandatory Description
name String Yes Name by which this card should be referred
card IdCard Yes The card to import

exportCard

Promise exportCard( String cardname )

Exports an network card. Should the card not actually contain the certificates in the card, a exportIdentity will be performed to get the details of the cards

Returns

Promise - resolved with an instance of the network id card populated

Parameters

Name Type Mandatory Description
cardName String Yes The name of the card that needs to be exported

getAllCards

Promise getAllCards( )

List all Business Network cards.

Returns

Promise - resolved with a Map of idcard objects keyed by their String names.

Parameters

No parameters

deleteCard

Promise deleteCard( String name )

Delete an existing card.

Returns

Promise - Resolves true if deleted, false if not deleted, is rejected if an error occurs.

Parameters

Name Type Mandatory Description
name String Yes Name of the card to delete.

hasCard

Promise hasCard( String name )

Has a existing card.

Returns

Promise - Resolves with true if the card with the name exists, resolved with false if not

Parameters

Name Type Mandatory Description
name String Yes Name of the card to check.

connect

connect( String cardname )

Connects and logs in to the Hyperledger Fabric using a named connection profile. The connection profile must exist in the profile store.

Parameters

Name Type Mandatory Description
cardName String Yes The name of the business network card

Example

// Connect to Hyperledger Fabric
let adminConnection = new AdminConnection();
try {
  await adminConnection.connect('userCard@network')
  // Connected.
} catch(error){
    // Add optional error handling here.
}

disconnect

Promise disconnect( )

Disconnects this connection.securityContext

Returns

Promise - A promise that will be resolved when the connection is terminated.

Parameters

No parameters

Example

// Disconnect from a Business Network
let adminConnection = new AdminConnection();
try {
  await adminConnection.connect('userCard@network')
  // Connected
  await adminConnection.disconnect()
  // and now disconnected.
} catch(error){
    // Add optional error handling here.
}

install

Promise install( String businessnetworkdefinition, Object installoptions )

Installs a business network as chaincode to Hyperledger Fabric in preparation for the business network to be started. The connection must be connected for this method to succeed.

Returns

Promise - A promise that will be fufilled when the business network has been installed

Parameters

Name Type Mandatory Description
businessNetworkDefinition String Yes The business network to be installed
installOptions Object Yes connector specific install options

Example

// Install the Hyperledger Composer runtime
let adminConnection = new AdminConnection();
let businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
try {
   await adminConnection.connect('adminCard@hlfv1')
   await adminConnection.install(businessNetworkDefinition);
   // Business network installed
} catch (error) {
    // Add optional error handling here.
}

start

Promise start( String networkname, String networkversion, [Object startoptions] )

Starts a business network within the runtime previously installed to the Hyperledger Fabric with the same name as the business network to be started. The connection must be connected for this method to succeed.

Returns

Promise - A promise that will be fufilled when the business network has been deployed - with a MAP of cards key is name

Parameters

Name Type Mandatory Description
networkName String Yes Name of the business network to start
networkVersion String Yes Version of the business network to start
startOptions Object Yes connector specific start options networkAdmins: [ { userName, certificate, privateKey } , { userName, enrollmentSecret }]

Example

// Start a Business Network Definition
let adminConnection = new AdminConnection();
try {
    await adminConnection.connect('userCard@network')
    await adminConnection.start(networkName, networkVersion,
             { networkAdmins:
                 [ {userName : 'admin', enrollmentSecret:'adminpw'} ]
             }

    // Business network definition is started
} catch(error){
    // Add optional error handling here.
}

reset

Promise reset( String businessnetworkname )

Resets an existing BusinessNetworkDefinition on the Hyperledger Fabric. The BusinessNetworkDefinition must have been previously deployed. Note this will remove ALL the contents of the network registries, but not any system registries IMPORTANT: Never use this api on a production or shared business network. It should only ever be used as a quick reset against a business network running locally on your machine for which you will not keep. Use this for your local development testing purposes only

Returns

Promise - A promise that will be fufilled when the business network has been updated.

Parameters

Name Type Mandatory Description
businessNetworkName String Yes The name of business network that will be reset

Example

// Resets a Business Network Definition
let adminConnection = new AdminConnection();
let businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
try {
   await adminConnection.connect('userCard@network')
   await adminConnection.reset('network-name')
   // Business network data removed
} catch(error){
    // Add error handling here.
}

upgrade

Promise upgrade( string businessnetworkname, string businessnetworkversion, [object upgradeoptions] )

Upgrades an existing business network to a later level.

Returns

Promise - A promise that will be fufilled when the composer runtime has been upgraded, or rejected otherwise.

Parameters

Name Type Mandatory Description
businessNetworkName string Yes The name of the business network
businessNetworkVersion string Yes The version of the business network
upgradeOptions object Yes connector specific options

Example

// Upgrade the Hyperledger Composer runtime
let adminConnection = new AdminConnection();
try {
   await adminConnection.connect('PeerAdmin@hlfv1')
   await adminConnection.upgrade('digitalproperty-network', '2.0.0');

   // Business network definition upgraded
} catch(error) => {
   // Add error handling here.
}

undeploy

Promise undeploy( String businessnetworkname )

Undeploys a business network.

Note: this this currently not supported with Hyperledger Fabric and will throw an error.

Returns

Promise - A promise that will be fufilled when the business network has been undeployed.

Parameters

Name Type Mandatory Description
businessNetworkName String Yes The name of business network to remove.

ping

Promise ping( )

Test the connection to the runtime and verify that the version of the runtime is compatible with this level of the node.js module.

Returns

Promise - A promise that will be fufilled when the connection has been tested. The promise will be rejected if the version is incompatible.

Parameters

No parameters

Example

// Test the connection to the runtime
let adminConnection = new AdminConnection();
try {
   await adminConnection.connect('userCard@network');
   await adminConnection.ping();
    // Connection has been tested
} catch(error){
    // Add error handling here.
}

setLogLevel

Promise setLogLevel( any newloglevel )

Set the logging level of a business network. The connection must be connected for this method to succeed.

Returns

Promise - A promise that resolves if successful.

Parameters

Name Type Mandatory Description
newLogLevel any Yes new logging level

Example

// Set the logging level of a business network.
let adminConnection = new AdminConnection();
try {
   await adminConnection.connect('userCard@network')
   await adminConnection.setLogLevel('DEBUG')
   console.log('log level set to DEBUG');
} catch(error){
    // Add error handling here.
}

getLogLevel

Promise getLogLevel( )

Get the current logging level of a business network. The connection must be connected for this method to succeed.

Returns

Promise - A promise that resolves with the current logging level if successful.

Parameters

No parameters

Example

// Get the current logging level of a business network.
let adminConnection = new AdminConnection();
try {
   await adminConnection.connect('userCard@network');
   let currentLogLevel = await adminConnection.getLogLevel();
    console.log('current log level is ' + currentLogLevel);
} catch(error){
    // Add error handling here.
}

list

Promise list( )

List all of the deployed business networks. The connection must be connected for this method to succeed.

Returns

Promise - A promise that will be resolved with an array of business network identifiers, or rejected with an error.

Parameters

No parameters

Example

// List all of the deployed business networks.
let adminConnection = new AdminConnection();
try {
   await adminConnection.connect('userCard@network');
   let businessNetworks = await adminConnection.list();
   businessNetworks.forEach((businessNetwork) => {
      console.log('Deployed business network', businessNetwork);
   });
} catch(error){
    // Add error handling here.
}

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