connector-configuration-reference.adoc

Connector Configuration Reference

There are two basic connector structures in Mule: 

• Operation-Based, and 

• Endpoint-Based structures.

This document describes the general configuration for both of these types. For instructions on usage of a specific connector, consult your desired connector’s documentation.

Note

HTTP connector in Mule 3.6 and newer As of Mule 3.6 and newer, the HTTP and HTTPS endpoint-based connectors and transports have been replaced by a single HTTP operation-based connector which supports HTTPS. The legacy endpoint-based HTTP connectors will be removed in a future version. For more information on the HTTP operation-based connector, see HTTP Connector.

Prerequisites

While you do not need full proficiency in Mule to configure connectors, you should be familiar with Mule and the Anypoint Studio interface. If you have not done so already, cement your understanding of the Mule application design process, and Studio:

• Build a Hello World Application

• Basic Studio Tutorial

Further, it is best you attain a basic understanding of Mule Application Flows, Global Elements, and Anypoint Connectors before moving on.

Basics

Operation-based connectors vary too widely to make generic configuration instructions possible. However, at minimum all operation-based connectors require a Connector Configuration and an Operation to run in a flow successfully. Connector configuration information should be defined in Global Elements for use and reuse in your application’s Mule flow(s). Operations are user-defined within each connector.

Configuring an Operation-Based Connector

Whether you are working in the Anypoint Studio Visual Editor or are crafting the XML code by hand, you must make a connector configuration for the connector in your Mule application to reference. This type of connector also requires an operation to perform.

Field	Description
Connector Configuration	Define global connection parameters in a Global Element that defines the connector configuration. Most operation-based connectors require the connection credentials be configured this way, at the global scope, accessible to any connector in the flow.
Operation	Select an operation from the dropdown to specify the function that the connector should perform against the API or protocol. For example, in the case of the GitHub connector, you have many operations to choose from, for example, "Get collaborator" or "Get commits"

[tab, title="Anypoint Studio Visual Editor"]
....
. *Drag and drop a connector* from the palette onto your canvas.
. Click the *Global Element* tab below the canvas in Anypoint Studio to *create a global element* where you define connector settings or properties.
.. Click *Create*, to define a new global element with the properties you require.
image:github-global-element-create.png[github-global-element-create]
+
.. Access the connector's properties using the Studio UI. A blank connector looks like this in the UI:
image:generic-connector-config-fields.png[generic-connector-config-fields]
... *Select* the global connector configuration element you created from the *Connector Configuration* dropdown.
... *Choose* an operation for the connector to perform.

....
[tab, title="XML Editor Approach"]
....
. If you decide not to use Anypoint Studio or its user interface, add the desired connector configuration to your code in the XML editor. The visual representation generates in Studio after you properly:
.. *Include* the predefined namespace and schema location of the connector in the *XML Configuration* file's header.
+
.GitHub Connector Namespace and Schema Location Example
[source,xml,linenums]
----
xmlns:github="http://www.mulesoft.org/schema/mule/github"
...
xsi:schemaLocation="
...
http://www.mulesoft.org/schema/mule/github http://www.mulesoft.org/schema/mule/github/current/mule-github.xsd
">
----
.. *Define* the global connector configuration in your XML. It should look like: `<connectorname:config name="ConnectorName__Configuration" user="username" pass="password"... />` with all its required fields set inside the brackets. This line of XML code goes above the flow's `<flow>` XML block.
.. *Reference* the configuration by specifying the global element's `name` attribute in the `config-ref` attribute of the connector. For example, the GitHub connector would use the global element called "GitHub__Configuration":
+
[source,xml,linenums]
----
<github:add-collaborator config-ref="GitHub__Configuration" doc:name="GitHub" owner="" repositoryName=""/>
----
.. *Select* an operation for the connector to perform.
....

Refer to a particular connector’s Technical Reference document for guidance on any fields you do not understand. You may access this material via Anypoint Exchange. There you can also discover which connectors are bundled automatically in Anypoint Studio.

Configuring an Endpoint-Based Connector

Endpoints pass messages into and out of a Mule flow, usually to external resources such as databases, Web clients, or email servers, but they can exchange messages with other Mule flows as well. 

Inbound Endpoints

An Inbound Endpoint, which resides at the beginning of a flow and acts as a Message Source, triggers a new flow instance each time it receives a message.

Each incoming message must follow the specific protocol supported by the receiving endpoint. For example, email can arrive on a POP3 or IMAP inbound endpoint, but files must use the FTP, File, or SFTP endpoints.

[tab,title="Studio Visual Editor"]
....

The POP3 component is acting as the inbound endpoint in the example flow:

image:connector_conf_inf_3.png[connector_conf_inf_3]
....
[tab,title="XML Editor"]
....
[source, xml, linenums]
----
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:jetty="http://www.mulesoft.org/schema/mule/jetty" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:pop3="http://www.mulesoft.org/schema/mule/pop3" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/jetty http://www.mulesoft.org/schema/mule/jetty/current/mule-jetty.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/pop3 http://www.mulesoft.org/schema/mule/pop3/current/mule-pop3.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <jetty:connector name="Jetty" configFile="a" resourceBase="a" doc:name="Jetty"/>
    <http:request-config name="HTTP_Request_Configuration" host="a" port="a" basePath="a" doc:name="HTTP Request Configuration"/>
    <pop3:connector name="POP3" backupFolder="a" moveToFolder="a" validateConnections="true" doc:name="POP3"/>
    <flow name="exampleflowwithinboundendp">
        <pop3:inbound-endpoint host="localhost" user="s" password="s" connector-ref="POP3" responseTimeout="10000" doc:name="POP3"/>
        <set-payload doc:name="Set Payload"/>
        <http:request config-ref="HTTP_Request_Configuration" path="s" method="s" doc:name="HTTP"/>
        <logger level="INFO" doc:name="Logger"/>
    </flow>
</mule>
----
....

Composite Sources

A special scope known as a Composite Source Scope allows you to encapsulate two or more connectors that receive the same type of data (for example, email, files, database maps, or HTML) into a single message processing block. Each embedded connector listens on its specific channel for incoming messages. Whichever connector receives a message first becomes the message source for that particular instance of the flow.

[tab,title="Anypoint Studio Visual Editor"]
....

There are two different message sources for this example flow, a *POP3* endpoint, and a *Jetty* endpoint.
image:composite-source-flow.png[composite source flow]

In Anypoint Studio Visual Editor you drag the *Composite Source* scope onto the canvas from your palette, then drag the connectors into the Composite Source scope processing block. The composite source then allows the each embedded connector to act as a temporary, non-exclusive message source when it receives an incoming message.
....
[tab,title="XML Editor"]
....
[source, xml, linenums]
----
<http:request-config name="HTTP_Request_Configuration" host="localhost" port="8083" doc:name="HTTP Request Configuration"/>
    <flow name="exampleflow2" >
        <composite-source doc:name="Composite Source">
            <pop3:inbound-endpoint host="localhost" user="${prod.user}" responseTimeout="10000" doc:name="POP3"/>
            <jetty:inbound-endpoint exchange-pattern="one-way" address="www.example.com" doc:name="Jetty"/>
        </composite-source>
        <set-payload doc:name="Set Payload" value="foo"/>
        <http:request config-ref="HTTP_Request_Configuration" path="/" method="POST" doc:name="HTTP"/>
        <logger level="INFO" doc:name="Logger" message="bar"/>
    </flow>
----

Add a composite-source tag into your flow, then embed multiple connectors inside the scope of the tag. The composite source then allows the each connector to act as a temporary, non-exclusive message source when it receives an incoming message.
....

Outbound Endpoints

If an endpoint-based connector is not the first building block (i.e., the message source) in a flow, it is designated as an outbound endpoint, since it uses the specific transport channel it supports (such as SMTP, FTP, or JDBC) to dispatch messages to targets outside the flow, which can range from file systems to email servers to Web clients and can also include other Mule flows.

In many cases, an outbound endpoint completes a flow by dispatching a fully processed message to its final, external destination. However, outbound endpoints don’t always complete flow processing, because they can also exist in the middle of a flow, dispatching data to an external source, and also passing that (or some other data) to the next message processor in the flow.

[tab,title="Anypoint Studio Visual Editor"]
....

Here we can see there is a POP3 connector being used as an inbound endpoint, but additionally, note there is a POP3 connector configured in the middle of the process side of the flow, as an _outbound_ endpoint.

image:outbound-endpoint-example-flow.png[outbound endpoint example flow]
....
[tab,title="XML Editor"]
....
[source, xml, linenums]
----
<flow name="exampleflow2" >      
   <pop3:inbound-endpoint host="localhost" user="${prod.user}" responseTimeout="10000" doc:name="POP3"/>     
   <set-payload doc:name="Set Payload" value="foo"/>
   <pop3:outbound-endpoint host="localhost" user="${prod.user}" responseTimeout="10000" doc:name="POP3"/>
   <logger level="INFO" doc:name="Logger" message="bar"/>
</flow>
----
....

Configuration Reference

While unique properties exist for various endpoint-based connectors, most of these building blocks share common properties.

The General tab often provides these fields.

Field	Description
Display Name	Defaults to the connector name. Change the display name, which must be alpha-numeric, to reflect the endpoint’s specific role, for example, Order Entry Endpoint
Exchange-Pattern	Defines the interaction between the client and server. The available patterns are one-way and request-response. A one-way exchange-pattern assumes that no response from the server is necessary, while a request-response exchange-pattern waits for the server to respond before it allows message processing to continue.
Host	The default name is localhost. Enter the Fully Qualified Domain Name (FQDN) or IP address of the server.
Port	The port number used to connect to the server. (For example, 80)
Path	Allows specification of a path. for example, /enter/the/path
Connector Configuration	Define global connection parameters.

Depending on the protocol and type (inbound or outbound); these additional parameters may appear on the General tab:

Field	Description
Polling Frequency	Time is milliseconds (ms) to check for incoming messages. Default value is 1000 ms.
Output Pattern	Choose the pattern from a drop down list. Used when writing parsed filenames to disk.
Query Key	Enter the key of the query to use.
Transaction	Lets you select the element to use for a transaction. Click the plus + button to add Mule transactions.
Cron Information	Enter a cron expression to schedule events by date and time.
Method	The operation performed on message data. Available options are: OPTION, GET, HEAD, POST, PUT, TRACE, CONNECT, and DELETE.

The Advanced tab often includes these fields.

Field	Description
Address	Enter the URL address. If using this attribute, include it as part of the URI. Mutually exclusive with host, port, and path.
Response Timeout	How long the endpoint waits for a response (in ms).
Encoding	Select the character set the transport uses. For example, UTF-8
Disable Transport Transformer	Check this box if you do not want to use the endpoint’s default response transport.
MIME Type	Select a format from the drop-down list that this endpoint supports.
Connector Endpoint	Define a global version of the connector configuration details.
Business Events	Check the box to enable default event tracking.

The Transformers tab often includes these fields.

Field	Description
Global Transformers (Request)	Enter the list of transformers to apply to a message before delivery. The transformers are applied in the order they are listed.
Global Transformers (Response)	Enter a list of synchronous transformers to apply to the response before it is returned from the transport.

Configuring Global Elements for Connectors

When developers create a Mule application utilizing connectors, they manage details and connection policy inside a "global element" that is accessible for as many connections as the developer cares to support. That means the connection information for API/service instances is saved inside a global element, accessible easily through the Studio UI or manually using the connector technical reference, available on each connector page or via Exchange - whether you like to drag and drop or code the Mule application XML code manually, the goal of the user guide is to make configuration easy, because swift and flexible development, testing and deployment is essential for.

Basically, a global element for a connector typically includes references to a username, password, and security tokens that are stored in a Properties File. There references can be stored securely within the global element. The references are typically in Ant syntax - ${my.ConnectionProperty} and are only a placeholder for the connection credentials and URIs.

If you already understand how to set connection attributes then the other consideration would be to ensure you are securely encapsulating your connection attributes as you require, inside the .properties or similar file, rather than within a global element itself. The .properties file usually lives within a resources folder .res within your application; rather than at the level of the connector instance in the flow.

This global connector configuration maintains the configuration and state, and many connectors of the same type in one application can reference the connector configuration at the global level. For example, a Mule application with four different HTTP connectors may all reference the same globally configured HTTP connector which defines specifics such as security, protocol, and proxy settings. Because they all reference the same global connector configuration, all four HTTP endpoints behave consistently within the application.

Selected global connector configurations can also be defined as Shared Resources for a domain and referenced by all applications for that same domain. For more information, see Shared Resources.

Note that the global element that you configure in Anypoint Studio is called a Connector Configuration and is nearly always referenced at the connector level. The connector consistently utilizes the connector configuration you carefully prepare, provided your connection credentials and settings are valid. Studio alerts you to problems in design time if you choose to use the UI’s Test Connection button or similar in the Global Element Properties Window. That is your hub for connector global element configuration within Studio.

Access the screen from the dropdown in the bottom window after selecting/clicking the connector in your flow. Note: make sure you configure the connector to authenticate and connect to the exact service instance you are permitted to access. When you design an application, make sure you initially use an account for your integration development purposes, rather than any account for production. The corresponding connector XML tags follow a standard format most of the time:

<connectorName>:config for operation-based connectors,

and for endpoint-based connectors: <connectorName>:connector

In Studio, if using the UI, you can quickly and simply set up an application that:

• uses connectors to hook into APIs or web services, listens to information administered by servers, maintains persistent connections to interact with databases and navigate external service architectures, send messages, pass them to other applications via Mule flow etc.

You can do all this using the fundamental integration development practices you have read above. Having understand Mule application development and managing connections to and from Mule means you can start to develop and hone an integration pattern you need to achieve. Even if you don’t understand how Mule works, you can take advantage of Mule by reading Mule application code, following development procedures that others have set up for you in Anypoint Exchange, or by reading step-by-step MuleSoft documentation, especially on pages from Mule 3.x and Studio 5.x versions and earlier. Use the version dropdown at the top to navigate to earlier material.

See Also

• Return to the Anypoint Connectors main page.