Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 6. Switchyard Project

A SwitchYard project is a Maven based project with the following characteristics:
  • a switchyard.xml file in the project's META-INF folder
  • one or more SwitchYard runtime dependencies declared in the pom.xml file
  • org.switchyard:switchyard-plugin Maven Old Java Object (MOJO) configured in the pom.xml file
A SwitchYard project may also contain a variety of other resources used to implement the application, for example: Java, BPMN2, DRL, BPEL, WSDL, XSD, and XML files.
The JBoss Developer Studio tooling supports the creation of new SwitchYard projects. The tooling also allows users to add SwitchYard capabilities to existing Maven projects.

6.1. Creating a New SwitchYard Project

Use the New SwitchYard Project wizard to create new SwitchYard project in your workspace.
The wizard creates a new project with the following structure:
  • a switchyard.xml file in src/main/resources/META-INF/ directory
  • a pom.xml file declaring SwitchYard runtime dependencies and configuration for the switchyard-plugin MOJO
  • a beans.xml file in src/main/resources/META-INF/ directory
  • a beans.xml file in src/test/resources/META-INF/ directory
  • a folder hierarchy for the specified Java package

Procedure 6.1. Create a New SwitchYard Project

  1. Click FileNewProject to start the New Project wizard. Click SwitchYardSwitchYard Project and then click Next.
  2. Enter the name and location for the new project and then click Next.
  3. Provide other details for the project.
    The library version can be specified directly using the Library Version field or indirectly by selecting a Target Runtime. Selecting a target runtime sets the library version to match the version provided by the target runtime.


    It is not necessary to select any components when creating the project. The tooling automatically configures components on the project as necessary.
  4. Click Finish to create the new project.
The SwitchYard editor displays the switchyard.xml file for the newly created SwitchYard project after the wizard finishes.

6.2. Importing Existing Maven Project

You can import the existing Maven projects to your workspace.

Procedure 6.2. Import a Maven Project

  1. Click FileImport to import the existing project. Click MavenExisting Maven Projects and then click Next.
  2. Click Browse and navigate to the directory where the project's pom.xml is located. Click OK.
  3. The pom.xml file for the existing project is displayed in the Projects section. Click the check box to select the desired POM file.
  4. Click Finish to start the importing process.
The SwitchYard editor displays the switchyard.xml file for newly created SwitchYard project after the wizard finishes.

6.3. Adding SwitchYard Capabilities to Existing Projects

SwitchYard capabilities may be added to existing projects in the workspace.


SwitchYard capabilities can only be added to Maven projects.

Procedure 6.3. Add SwitchYard Capabilities to Existing Project

  1. Right-click the project and click SwitchYardConfigure Capabilities to add (or modify) SwitchYard capabilities.
  2. The SwitchYard Settings dialog is displayed. Modify the settings as required. Click OK to update the configuration.
    Changes are reflected in the pom.xml file and switchyard.xml file.

6.4. Editing SwitchYard Projects

6.4.1. Editing the SwitchYard Configuration File

The JBoss Integration and SOA Development plug-in for JBoss Developer Studio provides a graphical editor for creating and maintaining your SwitchYard configuration file (switchyard.xml).
Assuming you have the plug-in installed, when you open a switchyard.xml file, by default it opens with the SwitchYard Visual Multipage Editor.
From here you can choose between three tabs (or views):
This is the primary graphical interface for building your SwitchYard application. From here you can interact with and configure each of the application's entities, and add new entities from the Palette. The visual design is automatically converted into XML which you can view from the Source tab.
In this tab you can set additional configuration such as Domain Properties and Security Configurations. You can also enable message tracing from here.
From the Source tab you can see the source XML which is generated automatically from the entities configured in the Design tab.


Users cannot modify the switchyard.xml file directly from the Source tab.
Q: Why should I use the graphical editor?
Q: How can I modify the switchyard.xml file directly within JBoss Developer Studio?
Why should I use the graphical editor?
  • The editor automatically manages dependencies for a project. For example, when you add a new binding or implementation to a composite, the editor adds the necessary info to switchyard.xml and the necessary Maven dependencies to the pom.xml. If you forget to update the pom.xml, the project fails to build (validate).
  • The editor automatically manages namespaces based on the features being used and the configuration level of the project.
  • The editor provides syntax and semantic validation, such as missing transformations and unused references.
How can I modify the switchyard.xml file directly within JBoss Developer Studio?
  1. Navigate to the src/main/resources/META-INF/switchyard.xml file in the Project Explorer window.
  2. Right-click on the file and select Open WithXML Editor.


  • Close the switchyard.xml file (as presented by the SwitchYard Visual Multipage Editor) before opening it with the XML Editor to avoid synchronization issues.
  • After completing your source edits, close the file and synchronize the model for the visual editor: right-click on the project in the Project Explorer, then select MavenUpdate Project.


The default editor for this file now is the XML Editor. To change it back to the graphical editor, right-click on the file and select Open WithSwitchYard Visual Multipage Editor.


Red Hat recommends using the graphical editor to prevent corruption of the switchyard.xml file. If the editor does not suit your needs, please consider submitting a request for enhancement.