// This module is included in the following assemblies:
// as_high-level-overview.adoc

:context: high
[id='description-of-constructs_{context}']
= Descriptions of {prodname} constructs

To use {prodname}, you create an
integration by working with connectors,
connections, actions, steps, and flows. It is helpful to have a basic understanding 
each of these constructs. 

Each installation of {prodname} is referred to as a {prodname} environment. 
When Red Hat installs and manages your {prodname} environment, it is running 
on OpenShift Online or on OpenShift Dedicated. When you install and manage 
a {prodname} environment, it is usually running on OpenShift Container Platform,
but it can be running on OpenShift Dedicated.

.Integrations
In {prodname}, there are simple integrations and API provider integrations.

A simple integration is a set of ordered steps that {prodname} executes. 
This set includes:

* A step that connects to an application to start the integration. This
connection provides the initial data that the integration
operates on. A subsequent connection can provide additional data. 

* A step that connects to an application to complete the integration. This
connection receives any data that was output from previous steps 
and finishes the integration. 

* Optional additional steps that connect to applications
between the start and finish
connections. Depending on the position of the additional connection
in the sequence of integration steps, an additional connection can
do any or all of the following:
+
** Provide additional data for the integration to operate on
** Process the integration data
** Output processing results to the integration

* Optional steps that operate on data between connections to
applications. Typically,
there is a step that maps data fields from the previous connection to
data fields that the next connection uses.

An API provider integration publishes a REST API service for which you
provided an OpenAPI schema. A call from a REST API client triggers execution
of an API provider integration. The call can invoke any operation that the
REST API implements. While a simple integration has one primary flow of execution, 
an API provider integration has a primary flow for each operation. Each operation
flow connects to the applications and processes the data according to the
steps that you added to that operation's flow when you created the integration. 
Each operation flow ends by returning a response that you specify 
to the client whose call triggered execution of the integration. 

.Connectors

{prodname} provides a set of connectors. A connector represents a specific
application that you want to obtain data from or send data to.
Each connector is a template
for creating a connection to that specific application. For example, you use the
Salesforce connector to create a connection to
Salesforce.

An application that you want to connect to might use the OAuth protocol
to authenticate users. In this case, you register your {prodname} environment 
as a client that can access that application. The registration is associated with the
connector for that application. You need to register a particular {prodname} 
environment only once with each 
application that uses OAuth. The registration extends to each 
connection that you create from that connector. 

If {prodname} does not provide a connector that you need, a developer
can create the required connector.

.Connections

Before you can create an integration, you must create a connection
to each application or service
that you want to obtain data from or send data to. 
To create a connection,
you select a connector and add configuration information. 
For example, to connect to an AMQ broker in an integration, you create
a connection by selecting the AMQ connector,
and then following prompts to identify the broker to connect to and the
account to use for the connection.

A connection is one specific instance of the connector that
it is created from. You can create any number of connections
from one connector. For example,
you can use the AMQ connector to create three AMQ connections where
each connection accesses a different broker. 

To create a simple integration, you select a connection to start the integration,
a connection to end the integration, and optionally one or more
connections for accessing additional applications.
To create an API provider integration, you can add one or more connections 
to each operation flow.
Any number of integrations and operation flows can use the same connection. A particular
integration or flow can use the same connection more than once. 

For details, see 
link:{LinkSyndesisIntegrationGuide}#connecting-to-applications_ug[About connections to applications that you want to integrate].

.Actions

In an integration, each connection performs exactly one action. As you create an
integration, you choose a connection to add to the flow and then you 
choose the action that the connection performs. For example, when you
add a Salesforce connection to a flow, you choose from
a set of actions that includes, but is not limited to,
creating a Salesforce account, updating a Salesforce account, and
searching Salesforce.

Some actions require additional configuration and {prodname}
prompts you for this information.

.Steps
A simple integration is a set of ordered steps. In an API provider 
integration, each operation flow is a set of ordered steps. 

Each step operates on data.
Some steps operate on data while connected to an application or service
outside {prodname}. These steps are connections. Between connections, there can
be other steps that operate on data in {prodname}.
Typically, the set of steps includes a step that maps data fields used
in a previous connection to data fields that are used in the next connection
in the flow.
Except for the start connection in a simple integration, 
each step operates on data it receives from the previous steps.

To operate on data between connections, {prodname} provides steps for:

* Mapping data fields in one application to data fields in another
application.

* Filtering data so that the integration continues only when the data
being processed meets criteria that you define.

* Spliting a collection of records into individual records so that 
{prodname} executes subsequent steps iteratively, once for each record.

* Aggregating individual records into a collection so that 
{prodname} executes subsequent steps once for the collection. 

* Generating equivalent, consistent output by inserting data into a
Freemarker, Mustache, or Velocity template.

* Logging information in addition to the default logging that {prodname}
automatically provides.

To operate on data between connections in a way that is not built into
{prodname}, you can upload an extension that provides a custom step.
See link:{LinkSyndesisIntegrationGuide}#developing-extensions_custom[Developing {prodname} extensions].

.Flow 
A flow is a set of ordered steps that an integration executes. 

A simple integration has one primary flow. 
An API provider integration has a primary flow for each operation that the REST API 
defines. Each operation's primary flow is the set of steps that processes 
a call that invokes that operation. 

A primary flow can have conditional flows. An integration evaluates a
condition that you specify to determine whether to execute its
associated flow. 

In a flow, each step can operate on the data that is output from
the previous steps. To determine the steps that you need in a flow, 
see 
link:{LinkSyndesisIntegrationGuide}#plan_ready[Considerations for planning your integrations].
