Neuron ESB Command Line Export/Import Deployment

The Neuron ESB Explorer, the main program that is used to create, modify and deploy Neuron ESB configurations, comes with the ability to export and import a configuration or specified parts of a configuration.

Figure 1: Import/Export menu from Neuron ESB Explorer

Figure 2: Export Neuron ESB Components dialog accessible through Neuron ESB Explorer File/Export menu

This Export/Import feature is accessible through the File menu of the Neuron ESB Explorer and is driven by a user interface. Using this tool, all or individual components of the solution can be selected for export or, a package of components can be selected to be imported into the current solution.

A drawback to using this feature directly through the Neuron ESB Explorer is if the user wants to export or import the same parts of a configuration multiple times (e.g. after making a change and they want to deploy only parts of it to a different machine).  If they were using Neuron ESB Explorer to do the export/import, they would have to choose the parts of the configuration that they needed each time within the user interface.

This is just one of several reasons why we’ve made the Import/Export capabilities available through a command line interface. The command line tool allows users automate repetitive tasks as well as to facilitate automated deployments and the inclusion of Neuron ESB deployments in larger build script scenarios.

In the previously described use case, rather than requiring a user to select the components to export each time, a response file can be created and fed into the command line interface as an argument. These response files can be manually constructed or created using the Import/Export dialog boxes accessible through the Neuron ESB Explorer.

A Response File is a simple text file that specifies the configuration objects to export/import which allows the exports and imports to be easily repeated.

Another case where the command line interface would be useful is if a user doesn’t want to load the configuration in Neuron ESB Explorer just to export/import it.  The command line interface makes it easy to do so without the need to load the Neuron ESB Explorer or the affected configuration.

Also, Windows batch scripts that call the command line interface can be created to automate the deployment of Neuron ESB solutions or updates to those solutions.

The ExportConfig.exe and ImportConfig.exe are the primary Neuron ESB command line programs are located in the Neuron ESB Instance directory (e.g. “C:\Program Files\Neudesic\Neuron ESB v3\DEFAULT” if installed in the default location)

Example of using the ExportConfig.exe program:

1. Open a Command Prompt window as Administrator

Figure 3: Administrator command prompt window

2. Enter “cd “C:\Program Files\Neudesic\Neuron ESB v3\DEFAULT”” to go to the default instance directory, if Neuron ESB was installed in the default location. Otherwise change directory to the instance directory where Neuron ESB is installed.

Figure 4: Change directory to the Neuron ESB instance’s installation folder

3. The format for running the ExportConfig.exe program is as follows:

ExportConfig.exe [options] path-to-directory path-to-esb-file

Where “path-to-directory” is the Neuron ESB configuration folder that you want to export elements from and “path-to-esb-file” is the path to the file that you want to save the exported elements to.  For example, if you wanted to export the Publisher called “ExamplePub” from the configuration saved in a folder “C:\NeuronESBConfiguration” to a file called “Export.esb” in the path “C:\”, you would enter this in the command window:

ExportConfig.exe --party=ExamplePub
“C:\NeuronESBConfiguration”  “C:\Export.esb”

Figure 5: Before running the ExportConfig.exe program

Figure 6: After running the ExportConfig.exe program successfully

You can type in “ExportConfig.exe” to see the multiple options that can be used.  Also, to export multiple elements, you can define multiple options.  To export two parties and two processes, you would enter:

ExportConfig.exe --party=Party1 --party=Party2 --process=Process1 --process=Process2 “C:\NeuronESBConfiguration”  “C:\Export.esb”

Note that if you enter a path to an existing esb file, that file will be overwritten with the new export.

Example of using the ImportConfig.exe program:

1. Open a Command Prompt window as Administrator

Figure 7: Administrator command prompt window

2. Enter “cd “C:\Program Files\Neudesic\Neuron ESB v3\DEFAULT”” to go to the default instance directory, if Neuron ESB was installed in the default location. Otherwise change directory to the instance directory where Neuron ESB is installed.

Figure 8: Change directory to the Neuron ESB instance’s installation folder

3. The format for running the ImportConfig.exe program is as follows:

 ImportConfig.exe [options] path-to-esb-file path-to-directory

Where “path-to-directory” is the Neuron ESB configuration folder that you want to import elements to and “path-to-esb-file” is the exported esb file that you want to import from.  For example, if you wanted to import the party called “ExamplePub” from the esb file saved at ”C:\ExportedConfig.esb” to a configuration in the path “C:\MyESBConfig”, you would enter this in the command window:

ImportConfig.exe --party=ExamplePub “C:\ExportedConfig.esb” “C:\MyESBConfig” 

Figure 9: Before running the ImportConfig.exe program

Figure 10: After running the ImportConfig.exe program

Notice that it prompted to see if you wanted to overwrite in the above screenshot.  This is because the party that was being imported already exists in the configuration that is being imported into.

You can type in “ImportConfig.exe” to see the multiple options that can be used.  Also, to import multiple elements, you can define multiple options.  So to import two parties and two processes, you would enter:

ImportConfig.exe --party=Party1 --party=Party2 --process=Process1 --process=Process2 “C:\ExportedConfig.esb”  “C:\ MyESBConfig”

Options

There are a number of options that can be used with the Neuron ESB command line interface. Options are used to indicate which objects to export/import from/to the configuration. Options have the following syntax:

--<option>=[“]object-name[“]

The double quotation marks are necessary if the object name contains spaces.

The following options have been defined for selecting and exporting/importing objects from/to the configuration:

• --acl: Exports/Imports an access control list from/to the configuration.
• --administrator: Exports/Imports an administrator from/to the configuration.
• --adapter-endpoint: Exports/Imports an adapter endpoint from/to the configuration.
• --adapter-policy: Exports/Imports an adapter policy from/to the configuration.
• --adapter: Exports/Imports an adapter from/to the configuration.
• --behavior: Exports/Imports a WCF behavior from/to the configuration.
• --binding: Exports/Imports a WCF binding from/to the configuration.
• --category: Exports/Imports all items for a category from/to the Neuron ESB configuration.
• --credential: Exports/Imports a credential from/to the configuration.
• --database: Exports/Imports a database from/to the configuration.
• --deployment-group: Exports/Imports a deployment group from/to the configuration.
• --environment-variable: Exports/Imports an environment variable from/to the configuration.
• --key: Exports/Imports a key from/to the configuration.
• --output: The path of the file to save the program’s verbose output to.
• --message-pattern: Exports/Imports a message pattern from/to the configuration.
• --process: Exports/Imports a process from/to the configuration.
• --service-endpoint: Exports/Imports a WCF service endpoint from/to the configuration.
• --service-policy: Exports/Imports a service policy from/to the configuration.
• --party: Exports/Imports a party from/to the configuration.
• --topic: Exports/Imports a topic from/to the configuration.
• --verbose: Tells the program to write a log to the path that the option “--output” is set to
• --wsdl: Exports/Imports a WSDL document from/to the configuration.
• --xml: Exports/Imports an XML document from/to the configuration.
• --xsd: Exports/Imports an XML schema document from/to the configuration.
• --xslt: Exports/Imports an XSLT transform from/to the configuration.
• --text: Exports/Imports a Text document from/to the Neuron ESB configuration.
• --json: Exports/Imports a Json document from/to the Neuron ESB configuration repository.
• --zone: Exports/Imports a zone from/to the configuration.
• --workflow: Exports/Imports a workflow from the Neuron ESB configuration.
• --workflow-endpoint: Exports/Imports a workflow endpoint from/to the Neuron ESB configuration.
• --availability-group: Exports/Imports an availability group from/to the Neuron ESB configuration.

Response Files

To make it easier to export/import the same objects or groups of objects multiple times, the programs recognize the presence of response files on the command line. A response file is a simple text file that contains one option per line. For example, a response file that exports/imports a topic, publisher, and subscriber would look like this:

--topic=Topic1

--party=Publisher1

--party=Subscriber1

To use the response file on the command line, prefix the path to the response file with an @ symbol. For example:

ExportConfig @”C:\TopicsAndParties.rsp” 
C:\NeuronESBConfiguration C:\Export.esb

Figure 11: Running the Export Program with a Response File

You can combine multiple response files and options on the command line. For example:

ExportConfig @TopicsAndParties.rsp @SalesServiceConnectors.rsp –

-process=ValidatePurchaseOrder C:\SalesConfiguration 

C:\Sales.esb

Summary

The Import/Export command line interface is a useful tool for deploying either partial or complete Neuron ESB solutions. Although many components of Neuron ESB solutions can be deployed via XCOPY, others cannot (e.g. document repository items). Also, using the import command line tools ensures that elements of the solution and their dependencies will be imported and updated in the correct order of their dependencies within the solution, which XCOPY does not address. Ultimately, the Neuron ESB command line tool is a great companion for those looking to streamline and automate their Neuron ESB deployments.