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

See also

Method Summary

Name Returns Description
connect Promise 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.
deploy Promise Deploys a new BusinessNetworkDefinition to the Hyperledger Fabric. The connection must be connected for this method to succeed.
disconnect Promise Disconnects this connection.securityContext
exportCard Promise 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
getAllCards Promise List all Business Network cards.
getLogLevel Promise Get the current logging level of a business network. The connection must be connected for this method to succeed.
hasCard Promise Has a existing card.
importCard Promise Import a business network card. If a card of this name exists, it is replaced.
install Promise Installs the Hyperledger Composer runtime to the Hyperledger Fabric in preparation for the business network to be started. The connection mustbe connected for this method to succeed. You must pass the name of the business network that is defined in your archive that this runtime will be started with.
list Promise List all of the deployed business networks. The connection must be connected for this method to succeed.
ping Promise Test the connection to the runtime and verify that the version of the runtime is compatible with this level of the node.js module.
reset Promise Resets an existing BusinessNetworkDefinition on the Hyperledger Fabric. The BusinessNetworkDefinition must have been previously deployed.
setLogLevel Promise Set the logging level of a business network. The connection must be connected for this method to succeed.
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. The connection must be connected for this method to succeed.
undeploy Promise Undeploys a BusinessNetworkDefinition from the Hyperledger Fabric. The business network will no longer be able to process transactions.
update Promise Updates an existing BusinessNetworkDefinition on the Hyperledger Fabric. The BusinessNetworkDefinition must have been previously deployed.
upgrade Promise Upgrades an existing business network's composer runtime to a later level. The connection must be connected specifying the business network identifier as part of the connection for this method to succeed.

Method Details

new AdminConnection()

Create an instance of the AdminConnection class.

Parameters

Name Type Optional Description
options Object true an optional set of options to configure the instance.

Sub-options

Name Type Optional Description
options.cardStore BusinessNetworkCardStore true 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

Parameters

Name Type Optional Description
name String false Name by which this card should be referred
card IdCard false 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 Optional Description
cardName String false 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 if an existing card was deleted; rejected otherwise.

Parameters

Name Type Optional Description
name String false 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 Optional Description
name String false Name of the card to check.

connect

Promise 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.

Example

// Connect to Hyperledger Fabric
var adminConnection = new AdminConnection();
adminConnection.connect('testprofile', 'WebAppAdmin', 'DJY27pEnl16d')
.then(function(){
    // Connected.
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

Promise - A promise that when resolved indicates the connection is complete

Parameters

Name Type Optional Description
cardName String false The name of the business network card

Example

// Connect to Hyperledger Fabric
var adminConnection = new AdminConnection();
adminConnection.connect('testprofile', 'WebAppAdmin', 'DJY27pEnl16d')
.then(function(){
    // Connected.
})
.catch(function(error){
    // Add optional error handling here.
});

disconnect

Promise disconnect( )

Disconnects this connection.securityContext

Example

// Disconnect from a Business Network
var adminConnection = new AdminConnection();
return adminConnection.disconnect()
.then(function(){
    // Disconnected.
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

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

Parameters

No parameters

Example

// Disconnect from a Business Network
var adminConnection = new AdminConnection();
return adminConnection.disconnect()
.then(function(){
    // Disconnected.
})
.catch(function(error){
    // Add optional error handling here.
});

install

Promise install( BusinessNetworkIdentifier businessnetworkidentifier, Object installoptions )

Installs the Hyperledger Composer runtime to the Hyperledger Fabric in preparation for the business network to be started. The connection mustbe connected for this method to succeed. You must pass the name of the business network that is defined in your archive that this runtime will be started with.

Example

// Install the Hyperledger Composer runtime
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.install(businessNetworkDefinition.getName())
.then(function(){
    // Business network definition installed
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

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

Parameters

Name Type Optional Description
businessNetworkIdentifier BusinessNetworkIdentifier false The name of business network which will be used to start this runtime.
installOptions Object false connector specific install options

Example

// Install the Hyperledger Composer runtime
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.install(businessNetworkDefinition.getName())
.then(function(){
    // Business network definition installed
})
.catch(function(error){
    // Add optional error handling here.
});

start

Promise start( BusinessNetworkDefinition businessnetworkdefinition, [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.

Example

// Start a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.start(businessNetworkDefinition)
.then(function(){
    // Business network definition is started
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

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

Parameters

Name Type Optional Description
businessNetworkDefinition BusinessNetworkDefinition false The business network to start
startOptions Object true connector specific start options startOptions.card the card to use for the NetworkAdmin

Example

// Start a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.start(businessNetworkDefinition)
.then(function(){
    // Business network definition is started
})
.catch(function(error){
    // Add optional error handling here.
});

deploy

Promise deploy( BusinessNetworkDefinition businessnetworkdefinition, Object deployoptions )

Deploys a new BusinessNetworkDefinition to the Hyperledger Fabric. The connection must be connected for this method to succeed.

Example

// Deploy a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.deploy(businessNetworkDefinition)
.then(function(){
    // Business network definition deployed
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

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

Parameters

Name Type Optional Description
businessNetworkDefinition BusinessNetworkDefinition false The business network to deploy
deployOptions Object false connector specific deployment options deployOptions.card the card to use for the NetworkAdmin

Example

// Deploy a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.deploy(businessNetworkDefinition)
.then(function(){
    // Business network definition deployed
})
.catch(function(error){
    // Add optional error handling here.
});

undeploy

Promise undeploy( BusinessNetworkIdentifier businessnetworkidentifier )

Undeploys a BusinessNetworkDefinition from the Hyperledger Fabric. The business network will no longer be able to process transactions.

Example

// Undeploy a Business Network Definition
var adminConnection = new AdminConnection();
return adminConnection.undeploy('identifier')
.then(function(){
    // Undeployed Business Network Definition
})
.catch(function(error){
    // Add optional error handling here.
})

Returns

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

Parameters

Name Type Optional Description
businessNetworkIdentifier BusinessNetworkIdentifier false The name of business network that will be used to start this runtime.

Example

// Undeploy a Business Network Definition
var adminConnection = new AdminConnection();
return adminConnection.undeploy('identifier')
.then(function(){
    // Undeployed Business Network Definition
})
.catch(function(error){
    // Add optional error handling here.
})

update

Promise update( BusinessNetworkDefinition businessnetworkdefinition )

Updates an existing BusinessNetworkDefinition on the Hyperledger Fabric. The BusinessNetworkDefinition must have been previously deployed.

Example

// Updates a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.update(businessNetworkDefinition)
.then(function(){
    // Business network definition updated
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

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

Parameters

Name Type Optional Description
businessNetworkDefinition BusinessNetworkDefinition false The new BusinessNetworkDefinition

Example

// Updates a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.update(businessNetworkDefinition)
.then(function(){
    // Business network definition updated
})
.catch(function(error){
    // Add optional error handling here.
});

reset

Promise reset( BusinessNetworkIdentifier businessnetworkidentifier )

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

Example

// Updates a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.reset(businessNetworkDefinition)
.then(function(){
    // Business network definition updated
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

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

Parameters

Name Type Optional Description
businessNetworkIdentifier BusinessNetworkIdentifier false The name of business network that will be reset

Example

// Updates a Business Network Definition
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.reset(businessNetworkDefinition)
.then(function(){
    // Business network definition updated
})
.catch(function(error){
    // Add optional error handling here.
});

upgrade

Promise upgrade( )

Upgrades an existing business network's composer runtime to a later level. The connection must be connected specifying the business network identifier as part of the connection for this method to succeed.

Example

// Upgrade the Hyperledger Composer runtime
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.connect(connectionProfileName, upgradeId, upgradeSecret, businessNetworkDefinition.getName())
.then(() => {
     return adminConnection.upgrade();
})
.then(() => {
    // Business network definition upgraded
})
.catch((error) => {
    // Add optional error handling here.
});

Returns

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

Parameters

No parameters

Example

// Upgrade the Hyperledger Composer runtime
var adminConnection = new AdminConnection();
var businessNetworkDefinition = BusinessNetworkDefinition.fromArchive(myArchive);
return adminConnection.connect(connectionProfileName, upgradeId, upgradeSecret, businessNetworkDefinition.getName())
.then(() => {
     return adminConnection.upgrade();
})
.then(() => {
    // Business network definition upgraded
})
.catch((error) => {
    // Add optional error handling here.
});

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.

Example

// Test the connection to the runtime
var adminConnection = new AdminConnection();
return adminConnection.ping()
.then(function(){
    // Connection has been tested
})
.catch(function(error){
    // Add optional error handling here.
});

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
var adminConnection = new AdminConnection();
return adminConnection.ping()
.then(function(){
    // Connection has been tested
})
.catch(function(error){
    // Add optional 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.

Example

// Set the logging level of a business network.
var adminConnection = new AdminConnection();
return adminConnection.setLogLevel('DEBUG')
.then(() => {
    console.log('log level set to DEBUG');
})
.catch(function(error){
    // Add optional error handling here.
});

Returns

Promise - A promise that resolves if successful.

Parameters

Name Type Optional Description
newLogLevel any false new logging level

Example

// Set the logging level of a business network.
var adminConnection = new AdminConnection();
return adminConnection.setLogLevel('DEBUG')
.then(() => {
    console.log('log level set to DEBUG');
})
.catch(function(error){
    // Add optional 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.

Example

// Get the current logging level of a business network.
var adminConnection = new AdminConnection();
return adminConnection.getLogLevel()
.then((currentLogLevel) => {
    console.log('current log level is ' + currentLogLevel);
})
.catch(function(error){
    // Add optional error handling here.
});

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.
var adminConnection = new AdminConnection();
return adminConnection.getLogLevel()
.then((currentLogLevel) => {
    console.log('current log level is ' + currentLogLevel);
})
.catch(function(error){
    // Add optional error handling here.
});

list

Promise list( )

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

Example

// List all of the deployed business networks.
var adminConnection = new AdminConnection();
return adminConnection.list()
.then((businessNetworks) => {
    // Connection has been tested
    return businessNetworks.forEach((businessNetwork) => {
      console.log('Deployed business network', businessNetwork);
    });
})
.catch(function(error){
    // Add optional error handling here.
});

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.
var adminConnection = new AdminConnection();
return adminConnection.list()
.then((businessNetworks) => {
    // Connection has been tested
    return businessNetworks.forEach((businessNetwork) => {
      console.log('Deployed business network', businessNetwork);
    });
})
.catch(function(error){
    // Add optional error handling here.
});